Part V · Contracts · Plate 02

Axon schema · DeltaReportV1

Axon describes the structural reach of a change. Soma uses that evidence to decide which curated concerns need checking.

Fig. 5.2.1   Writer and reader

1. Axon · writer

   Indexes the repository and produces a change-set-bound DeltaReportV1 envelope.

2. DeltaReportV1 · carrier

   Changed symbols, reachable entry surfaces, module dependents and index-trust evidence.

3. Soma · reader

   Matches that structural reach against concern triggers. A report is evidence, not a passing verdict.

Note 5.2.1   Reading the report

Start with changeSet to identify the evaluated revision, then touched, downstream and modules for structural reach. Read trust and truncation information before interpreting an empty result. The authoritative schema and field definitions follow below.

Listing 5.2.1   Inspect and evaluate

In an initialized repository with the tools installed, inspect the report or run the closeout gate. These are separate commands, not a JSON pipeline:

axon index
axon delta --json
cns gate

The gate refreshes the index when present, verifies Soma's maps and checks concerns. It is structural by default; live rubric evaluation requires explicit opt-in. See installation prerequisites before trying these commands.

2. Axon ↔ Soma Connectome & Delta Contracts

2.1 SQLite Schema v18 (.axon/axon.db)

Axon materializes the repository connectome into .axon/axon.db (WAL mode, single-transaction batch replacement) read directly by Soma (crates/soma-axon):

Schema v18 (S8) removed four tables nothing wrote or read: experts, expert_sessions, events, and knowledge_entries (with its FTS table knowledge_entries_fts). They were created by every v1 to v17 database and never populated by any organ. On the first write-open of an older database, Axon drops each group only if it is empty; a group that someone populated by hand is kept and named in index_metadata.v18_retained_tables rather than destroyed. Read-only opens (axon status, Soma) do not migrate. Soma, Engram, Cortex and Thalamus have no reader of these tables (deploy/dead-channels.sh proves it).

2.2 DeltaReportV1 JSON Contract (axon delta --json)

Soma (soma concerns check --axon axon or --delta <file>) consumes Axon's DeltaReportV1 envelope and enforces strict SHA and working-tree binding (StructuralDepth::bind):

Computed vs not computed. A field that Axon does not compute is null or absent, never 0 or [], so a reader cannot mistake "not computed" for "computed and empty". As of Axon S2 the following are NOT computed:

Everything else in the report is computed. The authoritative list is the NOT_COMPUTED table and module documentation in axon/crates/axon-delta/src/lib.rs. Soma reads none of the not-computed fields and parses both shapes.

The following abbreviated envelope uses a synthetic Example namespace and fictitious Billing/Reporting modules; it is not application or customer data. Ellipses indicate omitted arrays, not literal JSON values.

{
  "schemaVersion": 1,
  "changeSet": {
    "base": { "ref": "HEAD~1", "sha": "0123456789abcdef..." },
    "head": { "sha": "fedcba9876543210...", "workingTreeIncluded": false },
    "files": [
      { "path": "src/Module/Billing/Services/InvoiceService.php", "renamedFrom": null, "indexTrust": "fresh" }
    ],
    "summary": { "added": 0, "modified": 1, "deleted": 0, "renamed": 0, "untracked": null }
  },
  "touched": {
    "files": 1,
    "evidenceEdges": null,
    "orphanedNodes": null,
    "changedSymbolIds": [
      "symbol:php:Example\\Core\\Module\\Billing\\Services\\InvoiceService::calculateTotal"
    ]
  },
  "downstream": {
    "budget": { "maxDepth": 4, "maxNodes": 500, "truncated": false },
    "symbols": [...],
    "entrySurfaces": [
      {
        "id": "surface:http:GET:/admin/api/invoices/{id}",
        "kind": "http",
        "hops": 2,
        "resolvedVia": "structural-walk",
        "weakestConfidence": "proven",
        "via": [
          "symbol:php:Example\\Core\\Module\\Billing\\Services\\InvoiceService::calculateTotal",
          "symbol:php:Example\\Core\\Module\\Reporting\\Http\\Controllers\\InvoiceReportController::show",
          "surface:http:GET:/admin/api/invoices/{id}"
        ]
      }
    ]
  },
  "modules": {
    "changed": ["Billing"],
    "dependents": [
      { "module": "Reporting", "referenceCount": 14 }
    ]
  },
  "crossRepo": {
    "symbols": [...]
  },
  "trust": {
    "overlay": "overlay-complete",
    "indexedCommit": "fedcba9876543210...",
    "staleFiles": 0,
    "absentFiles": 0,
    "warnings": []
  }
}