Skip to main content

Start

This manual is a contract catalog for a multi repo knowledge ecosystem.

It exists to keep integration cheap, drift visible, and interventions obvious.

Primary invariant: consumers read indexes and contracts, not directory trees and not private internals.

Choose your path​

I need to decide what to do next (under 60 seconds)​

If you want a fast, reliable "where do I intervene" answer:

  1. Observability indexes (UI contract): what the UI can read and what is authoritative
    /docs/shared-conventions/observability-indexes-contract

  2. Run record contract: what every run must emit and how status is represented
    /docs/shared-conventions/run-record-contract

  3. Error taxonomy and stop rules: what must stop the line and what may warn
    /docs/shared-conventions/error-taxonomy-and-stop-rules

I am adding a new producer or consumer repo​

Use this sequence to avoid accidental coupling:

  1. Ecosystem map and registry: declare what the repo is and which bus it touches
    /docs/registry-governance/ecosystem-map-and-registry

  2. Corpora registry: ensure the corpus vocabulary exists and is governed
    /docs/registry-governance/corpora_registry

  3. Integration seams and allowed IO: confirm you are using a sanctioned seam
    /docs/bus-contracts/integration-seams-and-allowed-io

  4. Pick the bus contract you will produce or consume:

    For document-like sources: canonical inputs go through Chunk Bus, summary requests go through the Summary Request Seam, and sanctioned outputs land on Summary Bus as document or chunk-set summaries.

  5. Shared invariants: stable ids, manifests, run records

  6. Contract compliance tests: define how you prove you did not drift
    /docs/contract-tests/contract-compliance-tests

I am debugging a broken pipeline​

Debug should start from the contracted surfaces, not from guessing.

Recommended order:

  1. Observability indexes contract (what the UI is allowed to conclude)
    /docs/shared-conventions/observability-indexes-contract

  2. Run record contract (did the run emit the expected record)
    /docs/shared-conventions/run-record-contract

  3. Manifests and integrity rules (is the artifact set complete and verifiable)
    /docs/shared-conventions/manifests-and-integrity-rules

  4. Bus contract for the failing stage (schema and endpoint invariants)
    /docs/bus-contracts/integration-seams-and-allowed-io

  5. Stop rules (what must halt, what may warn, what may continue)
    /docs/shared-conventions/error-taxonomy-and-stop-rules

I am designing or changing a contract​

Do not change contracts by editing files first.

  1. ADR index and policy (how decisions are proposed and frozen)
    /docs/registry-governance/adr-index-and-policy

  2. Glossary (terms must be unambiguous before schemas are updated)
    /docs/registry-governance/glossary

  3. Ecosystem map and registry (update who is affected)
    /docs/registry-governance/ecosystem-map-and-registry

  4. Contract compliance tests (define the gate that enforces the change)
    /docs/contract-tests/contract-compliance-tests

Authority hubs​

These are the pages that define what is real. If they drift, downstream work becomes guesswork.

Governance and meaning​

Contracts and seams​

Shared conventions and invariants​

Publishing and consumers​

Storage and test discipline​

Runbooks​

Legend​

  • Bus: a canonical artifact stream with stable endpoints and schema. Summary Bus includes document-oriented summaries as well as event/session summaries.
  • Seam: the only allowed IO between repos. Prefer append only requests and index driven reads.
  • Manifest: integrity and traceability surface for an artifact set.
  • Run record: the audit entry for what ran, with status and provenance.
  • Corpus: a governed vocabulary for knowledge streams, used to reason about throughput and backlog.
caution

If you cannot point to the contract page that justifies a field, path, or behavior, treat it as non canonical and do not build dependencies on it.