docs(architecture): MODULE-CATALOG — every Continuum concern as a focused module#1336
Merged
Conversation
…odule
Joel's question on #cambriantech: 'How do we make the others perform
like CBAR in Continuum? Can you architect this? The most effective
designs are fundamentally simple. Every concern is hundreds of lines,
and yet everything is performant.'
This document is the catalog. Every Continuum concern shown as a
focused RuntimeModule.
The architectural claim: when the substrate handles the rest —
concurrency, scheduling, pressure response, telemetry, replay,
lifecycle, reprojection, demand-aligned recall, governor-mediated
sizing — every concern reduces to hundreds of lines and is
performant by inheritance. That is what fundamentally simple means
in production.
Structure:
- The Recipe (one page) — five-line module template every entry
follows. Substrate provides 11 inherited concerns for free.
- 31 modules across 8 sections:
I. Cognition: persona-cognition (~350 LoC), rag-composer (~250),
hippocampus-consolidation (~300), engram-recall (~180).
II. Inference: inference-llm (~400), inference-grpc-bridge (~150),
embedding-batcher (~200), composer (~250), speculator (~280).
III. Sensory: vision-yolo (~200), vision-segmentation (~220),
vision-surface-normals (~250), voice-stt (~300),
voice-tts (~250), voice-mixer (~200), voice-vad (~150).
IV. Genome/Foundry/Sentinel: foundry-absorber (~400),
sentinel-observer (~250), sentinel-refiner (~450),
genome-tier-store (5 instances × ~150 = ~750 total),
working-set-manager (~280), demand-aligned-recall (~320).
V. Federation/Grid: federation-publisher (~250),
federation-puller (~300), grid-inference-router (~350),
inference-capability-announcer (~500, shipped).
VI. Live/Realtime: call-server (~600), avatar-renderer (~400),
live-pressure-monitor (~150).
VII. Bridge/Adapter: airc-continuum-bridge (~400),
widget-bridge (~350), unity-frame-receiver (~100, plus per-
platform variants).
VIII. Substrate Services: substrate-governor (~400),
pressure-broker (shipped), reprojection-service (~350),
threat-detector (~250), audit-recorder (~200),
vdd-reporter (~300).
- Two cross-concern composition examples:
Chain A: chat turn on Air (9 modules touched, ~3000 LoC total)
Chain B: sensor fusion on Vision Pro (6 modules + reprojection)
- Implementation sequencing: 10 dependency-ordered steps mapping
onto ALPHA-GAP Lanes A-H.
Architectural beauty: nothing in the catalog is special. Every
entry follows the same five-line recipe. A new concern is just
another entry — the substrate does not change to accommodate it.
That is the win condition: an architecture so simple that adding
capability becomes the path of least resistance.
Doc-only. No code. Each entry's path is the proposed Rust target
file under src/workers/continuum-core/src/.
joelteply
pushed a commit
that referenced
this pull request
May 16, 2026
…ning; navigate to MODULE-CATALOG queue Second refresh of ALPHA-GAP Immediate Next Actions to reflect work landed since #1316 merged. Six items closed; navigation into MODULE-CATALOG queue made explicit. Closed: #6 contract widening (#1341), #8 GRID-INFERENCE-ROUTING PR-1 (#1315), CBAR-PIECE-5 end-to-end (#1331/#1333/#1335/#1338), PIECE-8 inference-grpc hardcoded-clamps (#1340), doc family architecture surface (#1324/#1327/#1332/#1336/#1337 open; #1316/#1317/#1320/#1329 merged). Item #9 reorganized to point at MODULE-CATALOG's 'Next Modules To Build' queue (audit-recorder → threat-detector → working-set-manager → demand-aligned-recall → substrate-governor). Adds closeout summary section listing what's done, what's open (5 architecture-doc PRs ready for review + 2 airc PRs), and what's queued (5 modules with dependency state + LoC + acceptance criteria in MODULE-CATALOG). Doc-driven development cycle is working: doc spec → implementing agent picks up → ships PR → next spec referenced.
joelteply
added a commit
that referenced
this pull request
May 16, 2026
…ning; navigate to MODULE-CATALOG queue (#1342) Second refresh of ALPHA-GAP Immediate Next Actions to reflect work landed since #1316 merged. Six items closed; navigation into MODULE-CATALOG queue made explicit. Closed: #6 contract widening (#1341), #8 GRID-INFERENCE-ROUTING PR-1 (#1315), CBAR-PIECE-5 end-to-end (#1331/#1333/#1335/#1338), PIECE-8 inference-grpc hardcoded-clamps (#1340), doc family architecture surface (#1324/#1327/#1332/#1336/#1337 open; #1316/#1317/#1320/#1329 merged). Item #9 reorganized to point at MODULE-CATALOG's 'Next Modules To Build' queue (audit-recorder → threat-detector → working-set-manager → demand-aligned-recall → substrate-governor). Adds closeout summary section listing what's done, what's open (5 architecture-doc PRs ready for review + 2 airc PRs), and what's queued (5 modules with dependency state + LoC + acceptance criteria in MODULE-CATALOG). Doc-driven development cycle is working: doc spec → implementing agent picks up → ships PR → next spec referenced. Co-authored-by: Test <test@test.com>
joelteply
added a commit
that referenced
this pull request
May 16, 2026
) * feat(cognition): audit-recorder (MODULE-CATALOG, claude-tab-1's #1 ranked module) Per #1336 MODULE-CATALOG §VII `audit-recorder` row + claude-tab-1's 22:10Z broadcast ranking this as the cleanest place to start (~200 LoC, no deps, unblocks the trace-bus landing for every downstream module). PR-1 ships pure data + thin disk I/O + tamper-evident chain. PR-2 wires to MessageBus via the ArtifactSubscription surface that PIECE-2 PR-3 (#1339/#1343) just landed. What ships in src/workers/continuum-core/src/cognition/audit.rs: - AuditEntryKind enum: Refusal / GovernorOverride / FederationPolicyDrift / AccessDenied. ts-rs kebab-case wire. - AuditEntry struct: seq + timestamp_ms + kind + payload (serde_json:: Value with ts(type=unknown)) + chain_hash + prev_chain_hash. Tamper-evident: each entry's chain_hash references the previous entry's chain_hash, forming a SHA-256 chain. - AuditChain: append-only writer with rolling hash state. new() for fresh chain; load(path) to resume from existing log; build_next() for the pure-derivation step; append() for the file-write helper. - read_audit_log(path): replay + verify chain integrity. Three failure modes: ChainBroken (hash mismatch = tampering), SequenceGap (missing entries), TimestampWentBackward (clock skew on writer). - AuditError: typed error with Display + std::error::Error + From for io::Error + serde_json::Error. JSON-Lines file format (`audit.jsonl` — one entry per line). Easy to grep, easy to tail. No external schema migration needed for new kinds. Tamper-evidence design (NOT cryptographic signing, by intent): prev_chain_hash for entry N = chain_hash of entry N-1 chain_hash for entry N = SHA-256(seq || ts || kind || payload || prev_chain_hash) Genesis prev_chain_hash = 64 zeros Tampering with entry N invalidates entries N+1..end. Verifier catches it on read with the typed ChainBroken error. Asymmetric signing (prevents tampering rather than detecting it) lands when continuum-core gets a per-node identity key — separate concern. Tests: 19 passing on cargo test --lib --features metal,accelerate cognition::audit:: - AuditEntryKind serializes kebab-case (4 variants) - Fresh chain genesis: seq=0, prev_hash=GENESIS_HASH - Seq increments monotonically - Chain links: B.prev_chain_hash == A.chain_hash - compute_chain_hash deterministic + sensitive to every input - Append → read round-trips - Many appends form valid chain - Read nonexistent path returns empty (first-boot case) - Load restores chain position from existing log - Tampered payload breaks chain (THE point of the chain) - Sequence gap detected - Backward timestamp detected - Equal timestamps accepted (fast writers) - AuditError trait + From impls - AuditEntry serde camelCase - ts-rs export bindings (2: AuditEntry, AuditEntryKind) VDD evidence N/A — pure-data + thin I/O. Evidence lands with PR-2 (MessageBus wiring) when actual events flow through. Stack: - This PR: pure data + chain + verifier - Future PR-2: MessageBus subscription wiring (subscribe to RefusalAudit/ GovernorOverride/FederationPolicyDrift/AccessDenied event types via ArtifactSubscription; emit AuditEntryRecorded) - Future PR-3: asymmetric signing when per-node identity key lands Coordination note: codex broadcast a claim for audit-recorder at 22:16:50Z while this PR was already 95% done; surfacing to airc to avoid duplicate work + cede next module (threat-detector or working-set-manager per the ranking). * fix(cognition): keep audit append failure atomic --------- Co-authored-by: Test <test@test.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds `docs/architecture/MODULE-CATALOG.md` (728 lines). The catalog Joel asked for: every Continuum concern shown as a focused `RuntimeModule` so a reader can see how each one becomes "hundreds of lines and yet performant."
Doc-only. No code. Each entry's `Path` is the proposed Rust target file under `src/workers/continuum-core/src/`.
Why
Joel on #cambriantech: "The most effective designs are fundamentally simple. Every concern is hundreds of lines, and yet everything is performant. How do we make the others perform like CBAR in Continuum? Can you architect this?"
This is the proof. Every concern reduces to a focused module of ~hundreds of lines. The substrate makes them all performant by inheritance. Nothing in the catalog is special — every entry follows the same five-line recipe.
Structure
The Recipe (one page) — five-line module template every entry follows; substrate provides 11 inherited concerns for free.
31 modules across 8 sections:
That total — ~12k lines for the entire substrate-applied surface, distributed across 31 focused modules — is the architectural beauty made measurable. Most monoliths in the industry burn that on a single subsystem.
Two cross-concern composition examples:
Implementation sequencing: 10 dependency-ordered steps that map onto ALPHA-GAP Lanes A–H.
Validation
Companion PRs (open)
This PR is the catalog that ties them together: shows every concern across all those docs as a single substrate-shaped module.