================================================================================
SDOA COMPENDIUM — BOOK II: GOVERNANCE & GATES
Edition: 5.4 — Sovereign Integration & Sleeve Amendment
Date: 27 June 2026
Classification: Canonical — Development Team Reference
Amendment Ribbon: v5.4 / 27-06-2026 / Sleeve Ratification
================================================================================

BOOK II — GOVERNANCE & GATES

§1  THE FOUR-STAGE STAGING PIPELINE
────────────────────────────────────────────────────────────────────────────────
Every new module, variant, or dynamic mutation must traverse this pipeline in
order. No stage may be skipped.

  [ 1. Synthesized ]  ──►  Generated by AI (Coach/Scaffold) or developer
          │
          ▼
  [ 2. Probation ]    ──►  ProbationOfficer static analysis + WASM sandbox
          │
          ▼
  [ 3. Human Sign-off ] ►  Developer reviews in IDE widget or CLI
          │
          ▼
  [ 4. Canonical ]    ──►  Sealed into portfolio/, registered in Registry

§2  PROBATIONOFFICER — THE STATIC ANALYSIS GATE
────────────────────────────────────────────────────────────────────────────────
File:     portfolio/substrate/workflows/ProbationOfficer.workflow.js
Version:  5.1.0

Rules enforced (all modules):
  LINE_LIMIT          Adapter/service/workflow: 200 lines max.
                      Primitive: 150 lines max.
                      Sleeve: 500 lines max.  ← v5.4
  FORBIDDEN_GLOBALS   No window.* write from Layer 3 modules.
  NO_EVAL             eval() and dynamic Function() constructors banned.
  LAYER_ISOLATION     L1 may not import L3; L2 may not import L3.

Sleeve rule pack (v5.4 — all five must pass for a sleeve to register):
  SLEEVE_NO_MUTATION          No fs.writeFileSync to peer module source files.
  SLEEVE_NO_EVAL              No eval() or Function() constructors.
  SLEEVE_NO_ABSOLUTE_PATHS    No [A-Za-z]:\\ hard-coded paths.
  SLEEVE_DECLARED_TRANSPORT_ONLY        No raw fetch() when transport is declared "https".
  SLEEVE_EXTERNAL_DECLARATION_REQUIRED  Sleeve MANIFEST must contain external block.

§3  REGISTRAR — THE INDEXING GATE
────────────────────────────────────────────────────────────────────────────────
File:     portfolio/authorities/registrar/Registry.service.ts
Version:  5.1.0

On module registration:
  1. validateManifest() checks all mandatory MANIFEST fields.
  2. For sleeve modules: validates external block has system, transport, commands.
  3. Resolves requires[] — fails if any dependency is absent.
  4. Adds module to the live registry map.
  5. Emits registry:moduleRegistered → Oracle rebuilds index.

SleeveExternal interface (v5.4):
  interface SleeveExternal {
    system:    string;
    transport: string;
    path:      string;
    commands:  string[];
  }

§4  ORACLE — THE CAPABILITY MESH
────────────────────────────────────────────────────────────────────────────────
File:     portfolio/substrate/services/Oracle.service.js
Version:  5.2.0

Oracle maintains a live, queryable index of every module's manifest surface.

Commands:
  query({ capability?, emitsEvent?, hasCommand?, runtime?, ... })
      → ranked CandidateResult[]

  whoHasBoundary({ system })     ← v5.4
      → sleeve modules wrapping the given external system

  describeModule({ moduleId })
      → full capability profile, including externalSystem/Transport/Commands

  dumpSurface({ layerFilter?, runtimeFilter? })
      → flat SurfaceEntry[] including surfaceType: "boundary" for sleeves

Scoring weights:
  Exact match on primary field    +10
  Exact match on secondary field   +5
  Fuzzy (substring) match          +2
  Sleeve latency < 200 ms          +3
  Sleeve latency > 2000 ms         −3   ← Phase 5
  Sleeve error rate > 20%          −5   ← Phase 5
  Sleeve error rate > 5%           −2   ← Phase 5
  Sleeve boundary fault count      −1 each (cap −5)  ← Phase 5

§5  TRIAGE — RUNTIME FAULT CONTAINMENT
────────────────────────────────────────────────────────────────────────────────
File:     portfolio/substrate/workflows/Triage.workflow.js
Version:  5.1.0

Triage is the runtime router and circuit breaker. It queries Oracle for the
capability surface, ranks candidates by Pulse telemetry, and dispatches.

Circuit breaker states:
  CLOSED      Normal operation.
  OPEN        Module (or sleeve boundary) has exceeded error threshold.
              No calls dispatched; fallback used if available.
  HALF_OPEN   After halfOpenAfterMs (30 s): one probe call allowed.

v5.4 additions:
  - _buildRoutingTable() includes surfaceType: "boundary" entries so sleeve
    external connections get circuit-breaker coverage.
  - triage:boundaryFault emitted when a sleeve external call fails.
    Payload: { moduleId, externalSystem, transport, error }
  - Chronicle logs every boundary fault for Cartographer drift analysis.

§6  COACH — THE SOLE HEALING PATH
────────────────────────────────────────────────────────────────────────────────
File:     portfolio/substrate/workflows/Coach.workflow.py
Version:  5.1.0

From v5.4 forward, Coach is the ONLY module permitted to apply code mutations.
No module may write to a peer's source file directly.

Healing flow:
  AiSleeve.healTestFailure()
    └─► heal:patch-request  (registry broadcast)
          └─► Coach.on_patch_request()
                ├─► reads target module source from registry
                ├─► applies patch string
                ├─► ProbationOfficer.run() [gate — must pass]
                └─► emits coach:mutationReady
                      └─► Registrar.fieldChampion(module)

Coach.run() (direct invocation from TestCore):
  1. Build LLM prompt from failures + manifest + source.
  2. Request patch from AiProvider.adapter.
  3. Extract code from response.
  4. Generate unified diff.
  5. Emit coach:mutationReady.
  6. Route through ProbationOfficer.

§7  CARTOGRAPHER — TOPOLOGY MAPPING & DRIFT DETECTION
────────────────────────────────────────────────────────────────────────────────
File:     portfolio/substrate/workflows/Cartographer.workflow.js
Version:  5.2.0

Cartographer builds the live dependency + event graph and renders it as SVG.

v5.4 additions (Phase 5):
  boundaryDrift({ since? }) command
    Compares each sleeve's external.commands against Chronicle telemetry:
      missingCommands  — in telemetry but NOT declared  → severity: critical
      extraCommands    — declared but never observed    → severity: medium/low
      pathMismatch     — >50% fault rate on boundary calls → severity: high
    Emits cartographer:boundaryDrift with summary and severity.

SVG rendering:
  ⟁  Sleeve boundary node        amber fill
  ⬚  Ghost external-system node  amber dashed outline
  ─ ─  Boundary edge             amber dashed

§8  THE CONSTITUTIONAL AMENDMENT PROCESS
────────────────────────────────────────────────────────────────────────────────
Rules are absolute. One-off exceptions are treated as structural violations.
When an engineering need conflicts with a constraint, a formal amendment is
required.

Amendment lifecycle:
  1. Identification        — cite the section and rule to be modified.
  2. Impact Analysis       — list all affected modules, schemas, interfaces.
  3. Migration Engineering — design a phased protocol maintaining full uptime.
  4. Ratification          — project lead signature; written to canonical ledger.
  5. Ledger Entry          — record in canonical amendment ledger; increment
                             SDOA version; update all documentation.

The constitution evolves only through governance — never through drift.

================================================================================
END OF BOOK II
================================================================================
