Vespa Engine — Root MOC

Vespa (~1.7M LOC, roughly equal Java and C++, ~150 flat top-level modules under vespa/) is
organized here into a Hybrid PARA + Evergreen Zettelkasten (Milner Bigraph) knowledge garden:

1. Subsystem Maps of Content (content/mocs/)

• container-jdisc — the stateless container (jDisc): request/response handling, component
  management, query/search middleware, document operations.
• content-nodes — the C++ data plane: storage, indexing, matching, ranking, distributed
  query execution.
• config-admin — configuration system and cluster administration: config server, config
  model, client libraries.
• utility-libs — cross-cutting utility libraries for C++ (vespalib) and Java (vespajlib).
• work-areas — sibling repos: pyvespa (Python client), skills (agent skills),
  documentation (Vespa docs site).
• garden-health — live Milner Bigraph topology, module coverage, open-question rollup, and parallel lease batches.

2. Domain Guides (content/guides/)

• search-ranking — multi-phase ranking pipeline (first-phase, second-phase, global-phase).
• schemas-app-packages — .sd schema compilation and application packages.
• querying-yql — YQL query parsing, scatter-gather dispatch, and distributed grouping.
• feeding-operations — /document/v1/, document processors, MessageBus, and distributor buckets.
• ai-rag — HNSW vector search, in-container ONNX/LLM embedders, and hybrid ColBERT RAG.

3. Evergreen Zettelkasten (zettels/, concepts/, invariants/, bridges/, evidence/, analyses/, contradictions/)

• Atomic Zettels: proton-lid-space-and-attribute-vectors, hnsw-single-pass-prefiltering, jdisc-stateless-searcher-chain-execution, messagebus-bucket-distribution-and-ideal-state.
• Concepts: milner-bigraph-knowledge-topology, vespa-tensor-type-system-and-algebra.
• Architectural Invariants (CRIT-001): inv-lid-monotonic-generation-guard, inv-jdisc-searcher-stateless-fill-discipline.
• Cross-Subsystem Bridges: bridge-java-cpp-tensor-serialization, bridge-config-model-to-proton-subscription.
• Evidence, Analyses & Contradictions: evid-vespa-subsystem-source-audit, evid-duckdb-wasm-and-verification-gates, analysis-vespa-code-map-module-coverage, cr-clustercontroller-subsystem-placement-and-skills-count.

4. PARA Actionable Lifecycle (projects/, areas/, resources/, archives/)

• Projects (para: project): project-unmapped-vespa-modules-harvest, project-hnsw-and-hybrid-rag-deep-dive.
• Areas (para: area): area-garden-governance-and-para-lifecycle, area-vespa-engine-subsystem-stewardship.
• Resources (para: resource): resource-vespa-cli-pyvespa-and-skills-reference.
• Archives (para: archive): archive-wave1-to-wave8-foundation-milestone.

Open questions

• Code-map covers “the modules you are most likely to encounter”; ~100 of ~150 modules are
  unmapped (e.g. fnet, search, vsm, linguistics, flags, logserver). Should any be
  folded into these MOCs or get their own notes?
• Confirm subsystem boundaries: clustercontroller-core is Java and sits between content
  and config concerns — Code-map places it under Content nodes (see cr-clustercontroller-subsystem-placement-and-skills-count).