| Authority | CANONICAL |
|---|---|
| Version | v1 |
| Last Updated | 2026-03-23 |
| Owner | Documentation Index |
| Scope | Documentation map and authority taxonomy |
| Change Rule | Tracks implementation |
Single-Source Rule: Every fact should have exactly one authoritative location. For the current production-contract doc set, authority level is declared in frontmatter rather than by directory placement. CI enforces explicit guards and generated-doc checks; it does not parse frontmatter to apply change rules.
New to the system? Read these in order:
- kernel — What "kernel" and "closed" mean
- current-architecture — What the v1 system looks like today
- kernel-prod-separation — Kernel/prod boundary and host/channel roles
- ontology — The four primitives and their causal roles
- execution — How graphs evaluate
- freeze — What is frozen vs patchable
- cluster-spec — Data structures for composition
- project-convention — SDK-first
Ergo project shape,
Cargo.tomlvsergo.toml, profiles, clusters, and crate layout - getting-started-sdk — Scaffold, run, validate, replay, and edit a real SDK-first Ergo project
- testing-notes — Practical notes from real project testing, including live ingress and current product edges
- ingress-channel-guide — HostedEvent ingress and process-channel authoring
- egress-channel-guide — Intent dispatch and durable-accept egress authoring
- concepts — Cluster composition concepts
- invariants — Enforcement loci for all invariants
- terminology — Canonical terms and usage
Directory structure is the topic map. No separate navigation aids needed.
- system/ Core laws and identity: ontology, execution model, freeze declaration, kernel closure, current architecture, kernel/prod separation, and terminology.
- orchestration/ Supervision and trust boundaries: supervisor spec and adapter contract.
- authoring/ Building projects, clusters, graphs, adapters, and boundary channels: project convention, getting-started guide, authoring concepts, cluster spec, YAML format, loader contract, testing notes, ingress channel guide, and egress channel guide.
- primitives/ Primitive implementation contracts: Source, Compute, Trigger, Action, and Adapter manifests.
- contracts/ External interface specifications: UI ↔ Runtime contract and extension roadmap.
- invariants/ Phase boundaries and enforcement: 220 tracked invariants across 16 phase files plus the generated rule registry.
- ledger/ Operational planning and doctrine risk tracking: closure register, dev-work ledgers, gap-work ledgers, and the decision log.
- plans/ Working design-loop documents: blast-radius maps, option analysis, scope shaping, and phased execution plans while the design loop remains active.
Current production-contract docs declare their authority in frontmatter. The active levels and their change rules:
- FROZEN Change rule: v1 required to change. Documents: ontology, execution, freeze, supervisor, and adapter.
- STABLE Change rule: additive changes only. Documents: concepts, cluster-spec, yaml-format, primitives/ (all five manifests), and rule-registry.
- CANONICAL
Change rule: tracks implementation.
Documents include: kernel,
current-architecture,
kernel-prod-separation,
terminology,
project-convention,
getting-started-sdk,
loader,
testing-notes,
ingress-channel-guide,
egress-channel-guide, and
invariants/ (all phase files plus INDEX), along with
canonical ledger records when their frontmatter declares
Authority: CANONICAL. - CONTRACTS Change rule: external interfaces. Documents: ui-runtime and extension-roadmap.
- PROJECT Change rule: working project/implementation records that track active design or delivery state. Documents: plans/ and operational ledger entries such as ledger/dev-work/.
- ESCALATION Change rule: exceptional authority record for conflict, override, or unresolved semantic risk that cannot be handled cleanly inside the normal decision/gap flow. Documents: specific escalation records when they exist.
- invariants/ tracks which invariants are enforced where, one file per phase.
- ledger/closure-register tracks semantic gaps and their resolutions.
- ledger/dev-work/ tracks implementation delivery, ledger/gap-work/ tracks doctrine/risk gaps, and ledger/decisions/ records authority outcomes.
- plans/ is the sanctioned pre-ledger or cross-ledger working area for iterative architecture/design loops that are not ready to be split cleanly across gap, decision, and dev-work files.
- All three reference spec documents (ontology, execution, etc.) as the source of truth.
- Decision records explain why a ruling was made. Top-level system, primitive, and authoring docs explain what the current system is.
READMEs under crates/ are informational for their respective packages.
They are not authoritative for system behavior.