Architecture

Inverted repository structure. Constitution is the root. Everything descends from it.

Governance Stack

┌─────────────────────────────────────────────────────────────┐
│                  CONSTITUTION                               │
│  constitution/CONSTITUTION.md (86 lines)                    │
│  Supreme governance. Immutable.                             │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────────┐
│                  TRUST DEED                                 │
│  deeds/TRUST_DEED.md (48 lines)                             │
│  TD-GAUNTLET-001. Multi-party obligations.                  │
│  deployment_allowed := security ∧ compliance                │
│                     ∧ logic ∧ human                         │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────────┐
│                  AGENT RUNTIME                              │
│  8 source files. 996 lines. Zero runtime dependencies.      │
│  HTTP server → Middleware → State machine → WORM ledger     │
│  Ed25519 signing → Hash chain → Atomic writes → File lock   │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────────┐
│                  SENTINEL REVIEW                            │
│  Security audit. Injection check. Auth verification.        │
│  25 findings. 15 patches. 0 remaining.                      │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────────┐
│                  LEAN PROOF LAYER                           │
│  3 files. 7 proven theorems. 2 sorry. 5 axioms.            │
│  TrustDeed.lean · TaskInvariants.lean · LedgerChain.lean    │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────────┐
│                  HUMAN APPROVAL                             │
│  OPERATOR: Jessica Westerhoff                               │
│  Final authority. Override power. Deployment gate.          │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────────┐
│                  DEPLOYMENT GATE                            │
│  4 conditions from Trust Deed:                              │
│  1. security_passed = true (SENTINEL approved)             │
│  2. compliance_passed = true (constitution satisfied)      │
│  3. logic_passed = true (tests pass)                       │
│  4. human_approved = true (operator signed)                │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────────┐
│                  WORM LEDGER                                │
│  Append-only JSONL. SHA-256 hash chain.                     │
│  Ed25519 signatures. Sealed segments.                       │
│  Atomic writes. File locking. Tamper-evident.               │
└─────────────────────────────────────────────────────────────┘

Source Files

File	Lines	Purpose
src/types.ts	50	AgentName, TaskStatus, LedgerEntryType, Task, LedgerEntry
src/hash.ts	37	SHA-256 hashing with | delimiters, timing-safe compare
src/validation.ts	57	Input validation, state transition validation
src/ledger.ts	196	WORM ledger, hash chain, sealed segments, signature verification
src/tasks.ts	184	Task CRUD, state machine, agent authorization
src/server.ts	281	HTTP server, signed middleware, regex routing
src/agent-keys.ts	132	Ed25519 keypair generation, signing, verification
src/file-lock.ts	101	File locking, atomic writes, PID stale detection

Task State Machine

pending ──→ in_progress ──→ completed
                │
                └──→ rejected

Valid transitions:
  pending     → in_progress
  pending     → rejected
  in_progress → completed
  in_progress → rejected

Terminal states: completed, rejected

Request Flow

HTTP Request
    │
    ▼
┌─────────────────────┐
│  parseBody()        │  100KB limit
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  requireSignedAgent │  Ed25519 verification
│  ├── agent in set?  │
│  ├── key matches?   │
│  ├── sig valid?     │
│  └── hash matches?  │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  Task Manager       │  State machine validation
│  ├── createTask     │
│  ├── startTask      │
│  ├── completeTask   │
│  └── rejectTask     │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  Ledger.append()    │  WORM entry
│  ├── hash chain     │
│  ├── signature      │
│  ├── atomic write   │
│  └── file lock      │
└─────────┬───────────┘
          │
          ▼
     HTTP Response

Hash Chain

Entry[i].hash = SHA256(
  seq | type | agent | timestamp | payload | prev_hash
)

Entry[i].prev_hash = Entry[i-1].hash

Entry[1].prev_hash = "0000...0000" (genesis)

Tamper detection:
  Modify Entry[3]
    → Entry[4].prev_hash mismatch → CHAIN BREAK
    → Recompute Entry[4].hash
    → Entry[5].prev_hash mismatch → CASCADE

File Tree