The Dual-Core Architecture: Hermetic Domain Isolation & Supply-Chain Provenance

A language model has no innate sense of architectural boundary. Given a flat working tree that mixes specifications, compiled engines, user interfaces, and host closures, it will treat every file as equally mutable context. The typical failure is not a syntax error. It is a cross-plane edge: an infrastructure flake edited to paper over a frontend layout bug; a substrate state machine relaxed to match a stale markdown contract; or a public handbook paragraph that silently absorbs a private client identifier.

Nomos treats this class of error as a topology problem, not a prompting problem. The repository graph is partitioned into the Dual-Core Architecture (ADR-0024 & ADR-0031). The compiled Go runtime, not the model, owns the edges between them. Documentation is not copied; it is projected with SHA-256 byte parity. Execution does not occur on trunk; it occurs in disposable, hermetic worktrees whose contents are hashed, gated across 42 Definition of Done gates, and—on release—bound to an immutable cryptographic release receipt.

This chapter specifies the canonical planes, the formal interface contracts, the atomic Two-Phase Commit release engine, and the supply-chain provenance chain that makes an autonomous agent's output auditable.

1. Why a Flat Graph Is Not a Substrate#

Early agentic repositories were organized by stack, team, or convenience: src/, docs/, infra/, web/ as folders inside one permission domain. Humans compensate for that mess with tribal knowledge. Models do not. They saturate context windows with unrelated files, invent import paths that compile locally while violating intended module boundaries, and treat a wiki paragraph as if it were a type.

Three fatal failure modes follow:

1. Cognitive Drift: Teleology, sensory UI, deterministic engines, and deployment manifests share a namespace. The model hallucinates dependencies that no human architect would draw.
2. Split-Brain Documentation: Specs live in a wiki; code lives in git. After a few cycles the two disagree, and the agent grounds itself on the stale document.
3. Provenance Collapse: A commit that mixes public handbook text with private ledger paths cannot prove clean-room origin. Legal, compliance, and operational audits all fail closed.

The design rule is mechanical:

The harness underneath the agent must expose the exact isolation topology the agent's reasoning is required to respect. If a plane boundary is not a filesystem, import, and git boundary, it is a suggestion. Suggestions are not invariants.

Nomos does not add an arbitrary "agent plane." The agent is a bounded transverse operator with an ephemeral CapBAC lease token and a step budget. The planes are the static fabric it is permitted to touch, strictly one task at a time.

2. The Dual-Core 2-Plane Singularity (ADR-0024 & ADR-0031)#

Under the Canonical Singularity Law (Law 6), Nomos formalizes the engineering lifecycle into strictly two architectural planes—the Intent Plane and the Substrate Plane—with Membrane (Observer Interfaces) and Infrastructure (Host Closures) operating as modular Substrate subsystems:

┌─────────────────────────────────────────────────────────────────────────────┐
│                       INTENT PLANE (The Conscious SSoT)                     │
│  - Formal Specifications, CUE Schemas, Architectural RFCs, Handbooks        │
│  - Task Namespace: INT-*                                                    │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │
                    Bilateral Twin Parity (Law 4)
                                       │
┌──────────────────────────────────────▼──────────────────────────────────────┐
│                    SUBSTRATE PLANE (The Physical Grounding)                 │
│  - Compiled Go Engine (nomos), AST Gatekeeper, SQLite State Machine         │
│  - Substrate Modules: Membrane (SvelteKit Cockpits) & Infra (NixOS Closures)│
│  - Task Namespace: SUB-*                                                    │
└─────────────────────────────────────────────────────────────────────────────┘

2.1 The Intent Plane (INT-*)#

• Core Question: Why does this capability exist, and what must deterministically remain true?
• Ontological Responsibility: Axioms, architecture, living specifications, formal contracts, public handbooks, CUE schema definitions, and the Single Source of Truth (SSoT) corpus.
• Artifacts: intent/ (the Living Vault): Markdown specifications with YAML frontmatter, RFC-class architectural decisions, protocol schemas under intent/runtime/schemas/*.cue.
• Negative Invariant: The Intent plane contains zero runtime execution logic. It specifies contracts; it does not compile binaries, mutate databases, or deploy servers.

2.2 The Substrate Plane (SUB-*)#

• Core Question: How does the system deterministically execute state transitions and verify invariants?
• Ontological Responsibility: The compiled Go engine (nomos), the lifecycle state machine (IDLE → PLAN → EDIT → REVIEW → SYNC → LEARN), AST analyzers, 42 Definition of Done quality gates, SQLite persistence, and transient task worktrees.
• Substrate Subsystems:
  • Membrane Module (substrate/membrane): Human-in-the-loop cockpits, SvelteKit portals, real-time telemetry visualizers.
  • Infrastructure Module (substrate/infra): Declarative NixOS closures, daemon supervisors, hardware inventories, networking.
• Negative Invariant: The Substrate core contains zero stochastic reasoning. Coding agents operate strictly under indirect control via CapBAC leases. Verification is binary: compilation exit code 0 and all 42 sensor probes green.

3. Formal In-Line Interface Contracts & DTO Schemas (Law 4)#

All task envelopes, verification vectors, and provenance receipts are governed by compiled Go DTOs and hash-verified CUE schemas:

3.1 Task Plane Envelope Contract (#TaskPlaneEnvelope)#

Governs task boundary isolation and prohibits multi-plane task mutations:

package schemas

// TaskPlaneEnvelope defines canonical plane scoping and task key boundaries.
#TaskPlaneEnvelope: close({
    task_key:     =~"^(INT|SUB)-[0-9]+$"
    plane:        "intent" | "substrate"
    burden:       int & >= 1 & <= 10
    allowed_roots: [...string]
    max_step_budget: int & > 0 & <= 100
})

3.2 Cryptographic Release Receipt Contract (#ReleaseReceipt)#

Formalizes the non-repudiation provenance certificate recorded to Git Notes (refs/notes/nomos/releases):

package schemas

// ReleaseReceipt encapsulates the cryptographic non-repudiation proof of an atomic release.
#ReleaseReceipt: close({
    task_key:         =~"^(INT|SUB)-[0-9]+$"
    trunk_commit:     string & =~"^[0-9a-f]{40}$"
    worktree_head:    string & =~"^[0-9a-f]{40}$"
    released_at:      string
    author:           string & != ""
    seat_telemetry: {
        seat:                string & != ""
        installed_from_repo: string & != ""
        rehydration_env:     string & != ""
    }
    walkthrough_path: string & != ""
    gates_passed:     int & >= 0
    gates_total:      int & >= 0
    gate_results:     [string]: bool
})

In Go, this is matched with byte-for-byte serialization parity by gitops.ReleaseReceipt in substrate/src/nomos/modules/gitops/release.go.

4. Atomic Two-Phase Commit Release Engine (Law 3 & Law 7)#

Releases in Nomos are not ad-hoc git push commands executed by agents. They are atomic transactions executed by the Substrate lifecycle engine over Git's object database:

  Worktree (feature/SUB-123)                    Trunk (main)
┌───────────────────────────────┐        ┌───────────────────────────────┐
│ 1. Prepare: nomos verify -v   │        │ Protected Trunk (Read-Only)   │
│    All 42 DoD Probes Pass     │        │ Locked against direct write   │
│    SHA-256 Digest Calculated  │        └──────────────┬────────────────┘
└──────────────┬────────────────┘                       │
               │                                        │
               ▼                                        ▼
┌────────────────────────────────────────────────────────────────────────┐
│ 2. Atomic 2PC Commit (git update-ref --stdin --atomic):                │
│    - Fast-Forward Merge: refs/heads/main -> worktree_commit            │
│    - Provenance Receipt: refs/notes/nomos/releases -> #ReleaseReceipt  │
│    - Teardown: Prune transient worktree & reset phase to IDLE          │
└────────────────────────────────────────────────────────────────────────┘

4.1 Atomicity & Crash Fault Tolerance#

To prevent TOCTOU (Time-of-Check to Time-of-Use) races and coordinator crash faults, the Phase 2 commit sequence invokes git update-ref --stdin --atomic. Both the trunk ref update (refs/heads/main) and the provenance receipt ref update (refs/notes/nomos/releases) succeed together or fail together in a single atomic OS-level transaction.

5. Dynamic Path Discovery & Zero-Hardcoded-Path Discipline (Law 5)#

Under Law 5, hardcoded filesystem literals (such as /home/... or hardcoded relative repository paths) are strictly prohibited across all tools and templates. All workspace boundaries and repository roots resolve dynamically via configuration discovery:

// Dynamic path resolution in Nomos Substrate
repoRoot, err := workspace.FindRepoRoot(".")
if err != nil {
    return nomoserrors.NewNomosError(nomoserrors.ErrCodeCore, "failed resolving repo root: %w", err)
}

cfg, err := config.LoadConfig(repoRoot)
if err != nil {
    return fmt.Errorf("failed loading dynamic SSoT configuration: %w", err)
}

// Intent and Substrate paths dynamically bound from registered ecosystem configuration
intentDir := cfg.Runtime.IntentDir

6. SSoT Projection & SHA-256 Byte Parity (Law 4)#

Documentation drift is treated as a state-replication defect. The Intent Plane (intent/) is the single authoritative source for specifications and handbooks. Downstream consumers (such as the SvelteKit Membrane portal) do not own separate content stores; they receive an automated compiled projection:

intent/designtime/handbook/**/*.md
        │  nomos intent sync
        ▼
  Strip / Validate SSoT Frontmatter
  Calculate Canonical SHA-256 Digest
        │
        ▼
  substrate/membrane/src/lib/handbook/content/**/*.md
        │
        ▼
  Assertion: SHA-256(Intent) == SHA-256(Membrane)

If a developer or agent edits a projected handbook file inside the Membrane without updating the Intent SSoT, the parity gate (nomos verify) detects the hash mismatch and aborts the release pipeline at ParityGate with exit code 1.

7. Table-Driven Test Matrix (Law 2)#

8. Summary of Architectural Invariants#

1. Dual-Core 2-Plane Singularity: Exactly two planes exist: Intent (INT-*) and Substrate (SUB-*). Membrane and Infrastructure are modular Substrate subsystems.
2. One Task, One Plane, One Worktree: Cross-plane mutations within a single task worktree are rejected closed.
3. Atomic 2PC Release: Trunk branch advancement and release receipt recording occur atomically via git update-ref --stdin --atomic.
4. Non-Verbal Provenance: Provenance is a cryptographic hash chain of Git objects and receipts—not a conversational chat log.
5. Bitwise SSoT Parity: Downstream documentation is a hash-verified projection of the Intent vault. No secondary authoring is tolerated.