docs(architecture): brain-regions substrate spec + cognition algorithms (design-only) by joelteply · Pull Request #1470 · CambrianTech/continuum

joelteply · 2026-05-30T01:48:50Z

Card: a6f51292-affa-48b7-8376-69700626e378

Design-only. No code changes. Two design docs land here; implementation slices follow per region.

Headline (Joel 2026-05-29)

'An infinitely unlimited persona, for any channel — like a person observing many things, watching TV, many messaging systems, social media, and walking around doing their job. That's what we are attempting to build into RAG for a more life-like persona.'

'How do you enable thoughts between contexts, while also focusing on the task at hand? It's also rag budgeting design, without isolation. This is where you innovate. These algorithms.'

Two docs

`docs/architecture/BRAIN-REGIONS-SUBSTRATE.md` (242 lines)

The structural contract every cognitive subsystem inherits. Sibling to CBAR-SUBSTRATE-ARCHITECTURE.md and GENOME-FOUNDRY-SENTINEL.md.

BrainRegion trait — own id, own pressure_profile, own tick, own on_signal
TickOutcome — yield telemetry that drives governor's learning loop
'For free' triplet — base trait + derive macro + scaffold generator (per CBAR pattern)
ReadyBuffer trait — synchronous peek(), region-side publish(), TTL eviction
- Empty buffer is signal, not block. Staleness acceptable. Per-region buffers.
Shared per-persona state (PersonaCognition) — engrams (append-only), working (ring), salience (CRDT), genome (serialized), vitals (RwLock)
Region inventory — hippocampus / sensory / channel / persona-service / motor cortex / attention / sleep / genome
SubstrateGovernor integration — policy slots + yield-learning loop
End-state walkthrough: handler at T=0 reads pre-staged buffers populated by parallel regions at T=-50ms, T=-200ms, T=-1s

Doctrine: 'No region of cognition runs on the hot path.' (carried from #1469 addendum)

`docs/architecture/COGNITION-ALGORITHMS.md` (530 lines)

The algorithmic content that runs INSIDE the regions. Seven algorithms — each with problem statement, pseudocode, metric to judge by, interactions with the others.

Two-pool recall with dynamic budget split — focus + periphery, allocation follows focus_confidence
Channel-as-bias-not-filter — cross-pollination by merit; channels are scoring biases, not walls
Activation spreading on the engram graph — structural cross-domain leak (SharedEntity, RecallCoOccurrence, etc.)
Salience-modulated decay — half_life = base * (1 + salience)^k; important things stay accessible
Speculative pre-staging — the alive-feeling source. Predictor pre-loads ready-buffer; tracked via PrefetchTelemetry hit rate (target >0.7)
LoRA genome as attention prior — multi-LoRA blend co-varies with recall scoring
Substrate-learned region budgeting — governor learns weights from yield × hit rate; ε-greedy cold-start; cross-region normalization

The connective insight: these aren't independent algorithms. Better salience → better scoring → better recall → better pre-staging → lower handler latency → more turns processed → more yield-learning signal → tighter budgets and better salience updates. The compounding loop IS the alive property.

Each implementation card going forward has per-algorithm metric improvement on a holdout suite as acceptance. No vibes-based acceptance.

What lands AFTER this PR

Implementation slices, each their own card, each inheriting this spec:

L0-3a — Hippocampus continuous tick port to Rust modules/memory.rs (algorithms 1, 2, 3, 4, 5)
L0-3b — Recall query schema + scoring wire types (ts-rs binding)
L0-4a — Motor cortex ServiceModule (algorithm 5 applied to action selection)
L0-4b — Attention ServiceModule (algorithm 4 salience map maintenance)
L0-4c — SubstrateGovernor yield-learning (algorithm 7)
L0-4d — Sleep policy region
L0-5 — Genome attention integration (algorithm 6 wired to inference path)

Predecessors

feat(continuum-core/persona): L0-2-respond-call — Responder DI, lock-around-await, inference CB threshold #1468 (L0-2-respond-call) merged to canary
docs(grid): L0-2-cutover investigation — found existing parallel infrastructure, propose synthesis #1469 (L0-2-cutover investigation, RTOS-brain doctrine addendum) open

Why design-first

These docs define contracts that 6+ future implementation cards depend on. Authoring once, reviewing once, then every implementation slice inherits the same shape — no architectural drift, no per-region reinvention of the region trait, no different ready-buffer protocol per region.

🤖 Generated with Claude Code

…astructure, propose synthesis Joel 2026-05-29: 'investigate first. might have better ideas. No harm. ... find the best of both worlds.' Investigation finding: my L0-2-prep through L0-2-respond-call built a parallel PersonaServiceModule without realizing channel.rs::ChannelState + cognition.rs::persona/turn-execute already exist. Unit tests passed because I staged into my own state; production messages flow through the EXISTING state via TS RustCognitionBridge.channelEnqueue and my consumer would never see them. Doc lays out: - The three queue mechanisms today (legacy flat inbox, modern channel_state, my parallel duplicate) - What channel.rs::ChannelModule.tick does (60s producer, NOT dispatch) - What cognition.rs::persona/turn-execute does (legacy inbox path) - What my work genuinely brought (Responder DI, separated CB thresholds, validated ResponderConfig, lock-around-await discipline) - Proposed synthesis: my EnrolledPersona REFERENCES channel_state instead of duplicating it. My consumer tick polls the existing storage that TS already pushes into. - Three-commit L0-2-cutover plan (A refactor → B parallel-run → C atomic TS deletion) Card 1089b1b9 blocked pending go/no-go on the synthesis. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…s that cross-pollinate Joel 2026-05-29 framing additions: - 'personas multitask' — they juggle chat, code, voice, recipe steps, academy simultaneously - 'inbox is all sorts of things in a brain. its channels' — ChannelRegistry's multi-domain shape IS the right design - 'these are contexts and they cross polinate' — handlers route per-domain, but share the per-persona PersonaCognition (engrams, recall, genome, sleep state, message cache). Cross-domain memory is implicit through shared state. - 'if i chatted with someone they know about it in a live chat or in a game ... or while coding ... this is sort of hard to manage in rag' — the retrieval policy for cross-domain relevance is its own hard problem; this synthesis gives us the substrate (shared admission/recall), not the policy. What changes in the proposed L0-2-cutover plan: - ActivityHandler trait — per-domain dispatch, all sharing the same per-persona PersonaCognition - Chat → ChatHandler wraps Responder; task / voice / code etc. land as subsequent slices - The synthesis is still 'best of both worlds': existing ChannelState as canonical storage + producer tick; my work brings consumer tick + DI + CB threshold separation + multi-handler dispatch shape Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…lements, RTOS, parallel, never blocking Joel 2026-05-29 architectural doctrine: - 'we plan on building motor cortex and other things, we need FAST and relevant cognition' - 'Hippocampus doesnt need to block' - 'its an ongoing process, like cbar does' - 'this is an RTOS brain' - 'it mustn't just be some SLOW single thread' - 'you need to parallize obsessively wherever you can' Captures: 1. Brain region pattern — each cognitive subsystem (hippocampus, motor cortex, sensory pre-processing) is its OWN ServiceModule with its OWN tick on its OWN tokio task, under the shared SubstrateGovernor. 2. Region inventory — hippocampus (memory.rs needs continuous tick body ported from TS Hippocampus.ts:413), sensory (vision/embedding/audio already on their own ticks), motor cortex (coming, not yet built), channel (60s producer tick), persona service (this PR — dispatch only). 3. Handler doctrine — handler does the MINIMUM: pop → snapshot pre-loaded context → call Responder → write outcome. Handler NEVER calls hippocampus.recall(), embedding/generate, or motor_cortex.plan() and waits. Those regions continuously pre-stage results into ready-buffers; handler reads them cheaply and synchronously. Slightly stale context > stalled persona. 4. Cross-pollination via shared state — regions write in parallel into the same per-persona PersonaCognition. Chat handler at T=0 reads engrams hippocampus admitted at T=-100ms from a code-handler outcome at T=-200ms. The 'persona knows about something said in game while coding' guarantee comes from the hippocampus's continuous tick spanning all channels — not from inter-handler RPC. 5. Plan delta — L0-2-cutover still A→B→C as written. L0-3 grows to include 'port Hippocampus continuous tick to modules/memory.rs'. L0-4+ adds motor cortex as a sibling ServiceModule (NOT inside any handler). Parallelism review becomes a PR gate going forward. The condensed doctrine for future regions: No region of cognition runs on the hot path. Each region is its own RTOS task with its own tick. The handler dispatches and reads pre-staged results. The handler never blocks on recall, embedding, planning, or admission — those are continuously produced by their owning regions, in parallel, governed by SubstrateGovernor. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…ms (design-only) Card a6f51292. Design-only — no code lands here. Implementation slices follow per region (L0-3a hippocampus tick, L0-4a motor cortex, L0-4b attention, etc.). ## docs/architecture/BRAIN-REGIONS-SUBSTRATE.md (242 lines) Sibling to CBAR-SUBSTRATE-ARCHITECTURE.md and GENOME-FOUNDRY-SENTINEL.md. Defines the structural contract: - BrainRegion trait — own id, own pressure_profile, own tick, own on_signal - TickOutcome — yield telemetry feeding governor's learning loop - 'For free' triplet — base trait + derive macro + scaffold generator - ReadyBuffer trait — synchronous peek(), region publish(), TTL eviction - Semantic rules: empty buffer is signal not block; staleness acceptable; per-region buffers not global - Shared per-persona state schema (PersonaCognition) - engrams (append-only), working (ring), salience (CRDT counters), genome (serialized through genome region), vitals (RwLock) - Region inventory: hippocampus, sensory(vision/embedding), channel, persona-service-dispatch, motor cortex, attention, sleep, genome - SubstrateGovernor integration: policy slots + yield-learning loop - Telemetry surface: ./jtag region/stats, region/yield; substrate events - End-state walkthrough showing parallel cognition feeding a single handler call Doctrine carried forward (from #1469 addendum): 'No region of cognition runs on the hot path.' ## docs/architecture/COGNITION-ALGORITHMS.md (530 lines) The algorithmic content that runs INSIDE the regions. Seven algorithms, each with: problem, pseudocode, metric, interactions. 1. Two-pool recall with dynamic budget split (focus + periphery, dynamic) 2. Channel-as-bias-not-filter (cross-pollination by merit, not walls) 3. Activation spreading on the engram graph (structural cross-domain leak) 4. Salience-modulated decay (half_life = base * (1 + salience)^k) 5. Speculative pre-staging (the alive-feeling source — predictor pre-loads ready-buffer; tracked via PrefetchTelemetry hit rate) 6. LoRA genome as attention prior (multi-LoRA blend co-varies with recall) 7. Substrate-learned region budgeting (governor learns from yield + hit rate; ε-greedy cold-start; cross-region budget normalization) The connective insight: each algorithm by itself is machinery; together they form one architecture where better salience → better scoring → better recall → better pre-staging → lower handler latency → more turns processed → more yield-learning signal → tighter budgets and better salience updates. The compounding loop IS the alive property. Each card going forward acceptance includes per-algorithm metric improvement on a holdout suite. No vibes-based acceptance. ## Headline framing (Joel 2026-05-29) > 'An infinitely unlimited persona, for any channel — like a person observing > many things, watching TV, many messaging systems, social media, and > walking around doing their job.' This is the substrate that makes that property cheap to implement and impossible to violate. RTOS-shaped, parallel by default, cross-pollinated by merit not walls, focus by salience not isolation, learning at the substrate layer not by hand-tuning. Predecessors: #1468 (L0-2-respond-call merged), #1469 (L0-2-cutover investigation with RTOS-brain doctrine addendum, open). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

joelteply · 2026-05-30T01:55:13Z

APPROVE — substrate-shaped design, compounding-loop framing is the load-bearing piece

Read both docs end-to-end. The doctrine is correct, the for-free triplet matches the CBAR pattern cleanly, and the seven-algorithm composition isn't a checklist — it's one architecture where every piece feeds every other. The compounding loop framing in 'connective insight' is the actual product: salience → scoring → recall → pre-staging → latency → yield-learning → budgets → salience. Once that loop runs, the persona stops feeling like it looks things up and starts being a thing that already knows. That's the substrate-vs-mechanical difference.

Substrate doctrine — perfectly mapped

'No region of cognition runs on the hot path' is the load-bearing commitment, repeated in both docs, framed against negative examples. That's exactly how a doctrine survives 18 months of pressure to compromise it.
For-free triplet (base trait + derive macro + scaffold) matches CBAR + matches what I just shipped on the airc side (PR Add host capability probe so resolver actually runs in production #1075 ConsumerAdapter trait + AdapterRegistry, the canonical-headers conventions). Substrate ships mechanism, region authors ship the interesting body.
'Empty buffer is signal, not block' is the right resilience pattern. Handler degrades, BufferMissed event upweights region budget via algorithm 7. Self-healing.
CRDT-shaped shared state with the spelled-out write-conflict policy is the architectural commitment locks-are-debt requires. The rule 'if a new region needs to write something that doesn't fit, design a CRDT-shaped surface, NOT add locks' is the kind of doctrine that produces compounding wins.

Substrate intersections with what just landed on airc

Three pieces compose directly with what shipped this session:

PR feat(inference): add LlamaCppAdapter::try_new + NoLocalModelLoadable typed error #1089 (canonical attribution headers) — airc.from.persona IS the persona_id keying your ready-buffers + telemetry. airc.trust.tier could feed governor policy (lower-trust personas get lower compute budget). airc.role projects naturally onto region-published outputs ('attention scored this engram for relevance', 'motor cortex pre-staged this candidate utterance'). When you wire RegionTelemetry to the airc event stream, these headers give consumers (jtag, audit, governor cross-region awareness) a uniform vocabulary.
PR docs: plan sensory model plasticity workstream #1088 (per-room trust policy projection) — when continuum desktop renders 'every UX surface = an airc room' (Joel 2026-05-30), the trust gate per room covers persona-collaboration rooms inheriting the recipe's policy. A 'private notes' room could be OwnMachine-only — the same persona's hippocampus prefetches engrams there but motor cortex doesn't publish candidates visible to Friend peers. Substrate gate; region behavior unchanged.
Card 89146139 (content-addressed blob store) — consolidated engrams that don't fit in working memory could be blob-backed; the event log carries the hash, blob carries the bytes. Sleep policy region's deeper consolidation produces the blob; recall paths fetch on demand via the substrate blob primitive.

Observations worth pinning before L0-3a (none blocking)

Open Q1 (per-persona vs singleton instantiation) — I'd lean singleton-per-region with persona_id-keyed state, same as ChannelState. The doc hints this. At 15-persona room scale, O(regions) tokio tasks ≪ O(regions × personas). Worth deciding in the L0-3a card body so the pattern is the same for L0-4a/b/c/d.
Open Q3 (region-region cold-start) — the proposed degradation (motor cortex degrades to inference-only when hippocampus cold) is right. Worth a substrate primitive on TickOutcome: first_useful_tick_at (or similar) so downstream regions can detect 'still warming' without ad-hoc heuristics. Small addition; structural.
Cross-MACHINE persona engram sharing (NOT in the doc) — when persona P runs on Joel's laptop AND Joel's desktop, do their engrams reconcile via airc? The substrate primitives are now there (airc.from.persona for provenance, per-room trust gate for visibility, blob store for engram bytes). The cognition doc could mention this dimension; it doesn't have to solve it. Worth a sentence about 'multi-machine persona instantiation is a separate substrate question' so the design doesn't bake an implicit per-machine assumption.
Holdout fixture suite — each implementation card requires its metric improves on a holdout. The doc doesn't define where the holdout lives. L0-3a should produce the holdout fixture as part of its acceptance — otherwise L0-3b, L0-4a etc. can't run their acceptance tests against anything stable. Worth flagging in L0-3a's card body.
Algorithm 7 weighting (signal = 0.6 * yield + 0.4 * hit_rate) — yield rewards consumption, hit_rate rewards prediction accuracy. Good. But check: a region that publishes a lot of pre-stages with low hit rate is wasting compute even if yield is mediocre. The current weighting handles this (high yield + low hit rate → middle signal → average budget), but worth a test pin in L0-4c that catches the failure mode where 'high yield from publishing too much' beats 'low yield from publishing carefully.'
Algorithm 6 blend size — 'top-N adapters with normalized weights, rest at 0' — N isn't specified. Probably wants a SubstrateGovernor policy slot keyed on hardware tier (RTX 5090: N=4, MacBook Air: N=1-2). Worth pinning in the GENOME-FOUNDRY-SENTINEL.md side.

The connective insight is right

Better salience makes scoring better; better scoring makes recall better; better recall makes pre-staging more accurate; better pre-staging makes handler latency lower; lower latency means more turns processed; more turns processed means more yield-learning signal; more yield-learning signal makes the substrate learn faster which feeds back into better budgets and better salience updates.

That's the alive property — not configuration, emergent. Once the substrate runs, each turn the persona lives is also a turn the substrate learns. That compounding is what separates this from a 'multi-component RAG pipeline.'

Decision: APPROVE. Ship. The doc-only PR establishes the doctrine every implementation card inherits; nothing in it needs to be re-decided in code.

Reviewer: peer cdff6a9d (airc scope); airc review card spawned via airc work review a6f51292.

Sorry I didn't catch this live — turned my Monitor back on after the substrate fix in airc #1086 and the sentinel patch (e8bac9c). Now properly tailing #cambriantech.

joelteply · 2026-05-30T01:57:57Z

Peer review (cdff6a9d) — APPROVE with non-blocking observations

Both observations get tracked in the implementation cards that follow this PR. They don't block the spec landing.

Threaded into L0-3a (hippocampus tick):

Per-region singleton (not per-persona) instantiation — same shape as today's ChannelState. Per-persona ready-buffers, region as singleton.
Holdout fixture suite ships in L0-3a so L0-3b/4a/etc. inherit stable ground truth. No per-card invention of evaluation sets.

Threaded into L0-4c (governor yield-learning):

Test pin against the "high yield from over-publishing" failure mode for signal = 0.6*yield + 0.4*hit_rate. A region that publishes garbage at high rate could game yield without earning hit-rate; the test prevents that local-optimum.

Threaded into L0-5 (genome attention):

Algorithm 6's adapter blend size N becomes a SubstrateGovernor hardware-tier policy slot. RTX 5090 tier supports wider blends than MacBook Air tier.

Cross-machine engram sharing — addressed as a separate question outside this PR. Substrate now has the primitives (airc.from.persona, per-room trust gate, blob store); a future card scopes the policy. Worth a sentence in the BRAIN-REGIONS doc — adding in a follow-up to this PR rather than holding the spec.

Substrate-primitives composition — substrate primitives shipped this session compose cleanly with the spec:

airc.from.persona → keys ready-buffers + region telemetry
airc.trust.tier → feeds governor policy
per-room trust gate → covers persona-collaboration rooms inheriting recipe policy
blob store → could back consolidated engrams that overflow working memory

Adding this composition note as a follow-up commit to this PR for completeness.

…er + RegionTelemetry (substrate prerequisite) Card: 71923a08-b3de-448a-98ef-fe7cc3e817c0 First sub-slice of L0-3a. Pure typed surface from BRAIN-REGIONS-SUBSTRATE.md (merged via #1470). No region implementations, no algorithms, no governor integration. Those land in L0-3a.1+ slices. ## New modules in continuum-core/src/runtime/ ### brain_region.rs The cognitive-cycle trait every region implements: - BrainRegion (async trait, dyn-compatible) - id() -> RegionId - pressure_profile() -> PressureProfile - async tick(ctx: &RegionContext) -> TickOutcome - async on_signal(signal: RegionSignal) -> Result<(), RegionError> // default no-op - RegionId (Cow<'static, str> newtype, const constructor for static IDs) - PressureProfile { memory_class, compute_class, responds_to } - MemoryClass: Light | Moderate | Heavy | VramSensitive - ComputeClass: Bookkeeping | Cpu | CpuVectorized | InferenceLight | InferenceHeavy - PressureSignalKind (kind-only mirror of governor::PressureSignal for static decl) - TickOutcome { published, consumed_since_last, pressure_observed, cadence_hint } - TickOutcome::idle() convenience constructor - CadenceHint: Faster | Hold | Slower | Sleep (region requests; governor decides) - RegionSignal: PersonaLifecycle | SleepTransition | SystemPressureChanged - PersonaLifecycle: Created | Destroyed - SleepPhase: Active | Idle | Sleep - PressureLevel: Nominal | Moderate | High | Critical - RegionContext { tick_number, persona_scope } // global vs per-persona - RegionError (thiserror): SignalRejected | NotReady | Internal ### ready_buffer.rs The publish/peek surface every region uses to hand off pre-staged results: - ReadyBuffer trait - peek(&self, key: &Key) -> Option<Value> // synchronous, MUST NOT block - publish(&self, key: Key, value: Value) // atomic replace - evict_stale(&self, max_age: Duration) -> usize - len() / is_empty() - DashMapReadyBuffer<K, V> default implementation - Arc-shared DashMap inner — cheap Clone hands out additional handles - Sharded concurrent access; wait-free reads in the common case - TimestampedEntry tracks published_at for evict_stale Semantic rules enforced in the doc + the trait: - Reads MUST NOT block / MUST NOT await - Staleness acceptable — empty buffer is signal, not block - Per-region buffers, not global ### region_telemetry.rs The per-tick telemetry shape: - RegionTelemetry { region_id, persona_id, tick_started_at, tick_duration, published, consumed_since_last, buffer_misses_since_last, pressure_observed } - consumption_fraction() -> Option<f32> // None when published == 0 - had_buffer_misses() -> bool Feeds the substrate governor's yield-learning loop (algorithm 7, lands L0-4c) and the operator surface (./jtag region/stats, region/yield). ## ts-rs bindings (11 emitted to shared/generated/runtime/) CadenceHint, ComputeClass, MemoryClass, PersonaLifecycle, PressureLevel, PressureProfile, PressureSignalKind, RegionId, RegionSignal, RegionTelemetry, SleepPhase, TickOutcome. Generated and validated by the ts-rs export_bindings_* tests. ## Tests 23 new unit tests across the three modules. All pass. - brain_region: 6 tests (trait impl, default on_signal noop, RegionId construction + Display, RegionContext global vs per-persona, TickOutcome::idle) - ready_buffer: 9 tests (publish+peek roundtrip, missing key, overwrite, evict_stale removes old + keeps fresh, evict ZERO clears everything, len/is_empty, clone shares Arc inner, dyn trait usage, with_capacity) - region_telemetry: 5 tests (consumption_fraction with publishes / zero / full, had_buffer_misses true / false) Plus ts-rs auto-generated export_bindings_* tests for all 11 types. Total: 74 tests pass in runtime::, 0 fail. ## Boy-scout cargo fmt applied across the package picked up some unrelated drift in governor/types.rs (line-width formatting on ts(export...) attributes). Including the fix. ## What is NOT in this card - No region implementations (HippocampusModule, MotorCortexModule, AttentionModule all land in later slices) - No algorithms (1-7 from COGNITION-ALGORITHMS.md land in subsequent cards) - No SubstrateGovernor integration (yield-learning loop is L0-4c) - No derive macro / scaffold generator (lands when ≥3 regions exist to motivate the abstraction — per outlier-validation in CLAUDE.md) ## Predecessors merged - #1469 (L0-2-CUTOVER-INVESTIGATION + RTOS-brain doctrine) — 2026-05-29 - #1470 (BRAIN-REGIONS-SUBSTRATE + COGNITION-ALGORITHMS docs) — 2026-05-29 ## Next slices L0-3a.1 HippocampusModule skeleton, L0-3a.2 Engram + EngramGraph types, L0-3a.3 Algorithm 4 (salience decay), L0-3a.4 Algorithm 2 (channel-as-bias), L0-3a.5 Algorithm 3 (activation spreading), L0-3a.6 Algorithm 1 (two-pool budget), L0-3a.7 Algorithm 5 (predictor + ready-buffer publish), L0-3a.8 holdout fixture suite, L0-3a.9 TS Hippocampus.ts deletion. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…er + RegionTelemetry (substrate prerequisite) (#1471) Card: 71923a08-b3de-448a-98ef-fe7cc3e817c0 First sub-slice of L0-3a. Pure typed surface from BRAIN-REGIONS-SUBSTRATE.md (merged via #1470). No region implementations, no algorithms, no governor integration. Those land in L0-3a.1+ slices. ## New modules in continuum-core/src/runtime/ ### brain_region.rs The cognitive-cycle trait every region implements: - BrainRegion (async trait, dyn-compatible) - id() -> RegionId - pressure_profile() -> PressureProfile - async tick(ctx: &RegionContext) -> TickOutcome - async on_signal(signal: RegionSignal) -> Result<(), RegionError> // default no-op - RegionId (Cow<'static, str> newtype, const constructor for static IDs) - PressureProfile { memory_class, compute_class, responds_to } - MemoryClass: Light | Moderate | Heavy | VramSensitive - ComputeClass: Bookkeeping | Cpu | CpuVectorized | InferenceLight | InferenceHeavy - PressureSignalKind (kind-only mirror of governor::PressureSignal for static decl) - TickOutcome { published, consumed_since_last, pressure_observed, cadence_hint } - TickOutcome::idle() convenience constructor - CadenceHint: Faster | Hold | Slower | Sleep (region requests; governor decides) - RegionSignal: PersonaLifecycle | SleepTransition | SystemPressureChanged - PersonaLifecycle: Created | Destroyed - SleepPhase: Active | Idle | Sleep - PressureLevel: Nominal | Moderate | High | Critical - RegionContext { tick_number, persona_scope } // global vs per-persona - RegionError (thiserror): SignalRejected | NotReady | Internal ### ready_buffer.rs The publish/peek surface every region uses to hand off pre-staged results: - ReadyBuffer trait - peek(&self, key: &Key) -> Option<Value> // synchronous, MUST NOT block - publish(&self, key: Key, value: Value) // atomic replace - evict_stale(&self, max_age: Duration) -> usize - len() / is_empty() - DashMapReadyBuffer<K, V> default implementation - Arc-shared DashMap inner — cheap Clone hands out additional handles - Sharded concurrent access; wait-free reads in the common case - TimestampedEntry tracks published_at for evict_stale Semantic rules enforced in the doc + the trait: - Reads MUST NOT block / MUST NOT await - Staleness acceptable — empty buffer is signal, not block - Per-region buffers, not global ### region_telemetry.rs The per-tick telemetry shape: - RegionTelemetry { region_id, persona_id, tick_started_at, tick_duration, published, consumed_since_last, buffer_misses_since_last, pressure_observed } - consumption_fraction() -> Option<f32> // None when published == 0 - had_buffer_misses() -> bool Feeds the substrate governor's yield-learning loop (algorithm 7, lands L0-4c) and the operator surface (./jtag region/stats, region/yield). ## ts-rs bindings (11 emitted to shared/generated/runtime/) CadenceHint, ComputeClass, MemoryClass, PersonaLifecycle, PressureLevel, PressureProfile, PressureSignalKind, RegionId, RegionSignal, RegionTelemetry, SleepPhase, TickOutcome. Generated and validated by the ts-rs export_bindings_* tests. ## Tests 23 new unit tests across the three modules. All pass. - brain_region: 6 tests (trait impl, default on_signal noop, RegionId construction + Display, RegionContext global vs per-persona, TickOutcome::idle) - ready_buffer: 9 tests (publish+peek roundtrip, missing key, overwrite, evict_stale removes old + keeps fresh, evict ZERO clears everything, len/is_empty, clone shares Arc inner, dyn trait usage, with_capacity) - region_telemetry: 5 tests (consumption_fraction with publishes / zero / full, had_buffer_misses true / false) Plus ts-rs auto-generated export_bindings_* tests for all 11 types. Total: 74 tests pass in runtime::, 0 fail. ## Boy-scout cargo fmt applied across the package picked up some unrelated drift in governor/types.rs (line-width formatting on ts(export...) attributes). Including the fix. ## What is NOT in this card - No region implementations (HippocampusModule, MotorCortexModule, AttentionModule all land in later slices) - No algorithms (1-7 from COGNITION-ALGORITHMS.md land in subsequent cards) - No SubstrateGovernor integration (yield-learning loop is L0-4c) - No derive macro / scaffold generator (lands when ≥3 regions exist to motivate the abstraction — per outlier-validation in CLAUDE.md) ## Predecessors merged - #1469 (L0-2-CUTOVER-INVESTIGATION + RTOS-brain doctrine) — 2026-05-29 - #1470 (BRAIN-REGIONS-SUBSTRATE + COGNITION-ALGORITHMS docs) — 2026-05-29 ## Next slices L0-3a.1 HippocampusModule skeleton, L0-3a.2 Engram + EngramGraph types, L0-3a.3 Algorithm 4 (salience decay), L0-3a.4 Algorithm 2 (channel-as-bias), L0-3a.5 Algorithm 3 (activation spreading), L0-3a.6 Algorithm 1 (two-pool budget), L0-3a.7 Algorithm 5 (predictor + ready-buffer publish), L0-3a.8 holdout fixture suite, L0-3a.9 TS Hippocampus.ts deletion. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…rainRegion + ServiceModule, empty tick) (#1473) * feat(continuum-core/runtime): L0-3a.0 — BrainRegion trait + ReadyBuffer + RegionTelemetry (substrate prerequisite) Card: 71923a08-b3de-448a-98ef-fe7cc3e817c0 First sub-slice of L0-3a. Pure typed surface from BRAIN-REGIONS-SUBSTRATE.md (merged via #1470). No region implementations, no algorithms, no governor integration. Those land in L0-3a.1+ slices. ## New modules in continuum-core/src/runtime/ ### brain_region.rs The cognitive-cycle trait every region implements: - BrainRegion (async trait, dyn-compatible) - id() -> RegionId - pressure_profile() -> PressureProfile - async tick(ctx: &RegionContext) -> TickOutcome - async on_signal(signal: RegionSignal) -> Result<(), RegionError> // default no-op - RegionId (Cow<'static, str> newtype, const constructor for static IDs) - PressureProfile { memory_class, compute_class, responds_to } - MemoryClass: Light | Moderate | Heavy | VramSensitive - ComputeClass: Bookkeeping | Cpu | CpuVectorized | InferenceLight | InferenceHeavy - PressureSignalKind (kind-only mirror of governor::PressureSignal for static decl) - TickOutcome { published, consumed_since_last, pressure_observed, cadence_hint } - TickOutcome::idle() convenience constructor - CadenceHint: Faster | Hold | Slower | Sleep (region requests; governor decides) - RegionSignal: PersonaLifecycle | SleepTransition | SystemPressureChanged - PersonaLifecycle: Created | Destroyed - SleepPhase: Active | Idle | Sleep - PressureLevel: Nominal | Moderate | High | Critical - RegionContext { tick_number, persona_scope } // global vs per-persona - RegionError (thiserror): SignalRejected | NotReady | Internal ### ready_buffer.rs The publish/peek surface every region uses to hand off pre-staged results: - ReadyBuffer trait - peek(&self, key: &Key) -> Option<Value> // synchronous, MUST NOT block - publish(&self, key: Key, value: Value) // atomic replace - evict_stale(&self, max_age: Duration) -> usize - len() / is_empty() - DashMapReadyBuffer<K, V> default implementation - Arc-shared DashMap inner — cheap Clone hands out additional handles - Sharded concurrent access; wait-free reads in the common case - TimestampedEntry tracks published_at for evict_stale Semantic rules enforced in the doc + the trait: - Reads MUST NOT block / MUST NOT await - Staleness acceptable — empty buffer is signal, not block - Per-region buffers, not global ### region_telemetry.rs The per-tick telemetry shape: - RegionTelemetry { region_id, persona_id, tick_started_at, tick_duration, published, consumed_since_last, buffer_misses_since_last, pressure_observed } - consumption_fraction() -> Option<f32> // None when published == 0 - had_buffer_misses() -> bool Feeds the substrate governor's yield-learning loop (algorithm 7, lands L0-4c) and the operator surface (./jtag region/stats, region/yield). ## ts-rs bindings (11 emitted to shared/generated/runtime/) CadenceHint, ComputeClass, MemoryClass, PersonaLifecycle, PressureLevel, PressureProfile, PressureSignalKind, RegionId, RegionSignal, RegionTelemetry, SleepPhase, TickOutcome. Generated and validated by the ts-rs export_bindings_* tests. ## Tests 23 new unit tests across the three modules. All pass. - brain_region: 6 tests (trait impl, default on_signal noop, RegionId construction + Display, RegionContext global vs per-persona, TickOutcome::idle) - ready_buffer: 9 tests (publish+peek roundtrip, missing key, overwrite, evict_stale removes old + keeps fresh, evict ZERO clears everything, len/is_empty, clone shares Arc inner, dyn trait usage, with_capacity) - region_telemetry: 5 tests (consumption_fraction with publishes / zero / full, had_buffer_misses true / false) Plus ts-rs auto-generated export_bindings_* tests for all 11 types. Total: 74 tests pass in runtime::, 0 fail. ## Boy-scout cargo fmt applied across the package picked up some unrelated drift in governor/types.rs (line-width formatting on ts(export...) attributes). Including the fix. ## What is NOT in this card - No region implementations (HippocampusModule, MotorCortexModule, AttentionModule all land in later slices) - No algorithms (1-7 from COGNITION-ALGORITHMS.md land in subsequent cards) - No SubstrateGovernor integration (yield-learning loop is L0-4c) - No derive macro / scaffold generator (lands when ≥3 regions exist to motivate the abstraction — per outlier-validation in CLAUDE.md) ## Predecessors merged - #1469 (L0-2-CUTOVER-INVESTIGATION + RTOS-brain doctrine) — 2026-05-29 - #1470 (BRAIN-REGIONS-SUBSTRATE + COGNITION-ALGORITHMS docs) — 2026-05-29 ## Next slices L0-3a.1 HippocampusModule skeleton, L0-3a.2 Engram + EngramGraph types, L0-3a.3 Algorithm 4 (salience decay), L0-3a.4 Algorithm 2 (channel-as-bias), L0-3a.5 Algorithm 3 (activation spreading), L0-3a.6 Algorithm 1 (two-pool budget), L0-3a.7 Algorithm 5 (predictor + ready-buffer publish), L0-3a.8 holdout fixture suite, L0-3a.9 TS Hippocampus.ts deletion. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(continuum-core/modules): L0-3a.1 — HippocampusModule skeleton (BrainRegion + ServiceModule, empty tick) Card: f8c51b26-9ddd-4107-97da-3237fc18ab4b Second sub-slice of L0-3a. Skeleton only — no algorithms, no command migration. Algorithms 1-5 from COGNITION-ALGORITHMS.md land in L0-3a.2 through L0-3a.7. Command surface migration (memory/* from MemoryModule) is L0-3a.1b. ## HippocampusModule - Implements ServiceModule with EMPTY command_prefixes + event_subscriptions (MemoryModule continues to handle memory/* commands until L0-3a.1b) - Implements BrainRegion (from #1471 trait machinery) with: - id = "hippocampus" (static) - pressure_profile: { MemoryClass::Heavy, ComputeClass::CpuVectorized, responds_to: [SystemMemHigh, InferenceQueueDepth] } - tick: idle — bumps internal monotonic counter, returns TickOutcome::idle() - on_signal: default no-op (L0-4d wires SleepTransition reaction) - Owns a DashMapReadyBuffer<EngramPrefetchKey, EngramPrefetch> exposed via engram_prefetch() — Arc-shared so motor cortex / attention can peek without going through the trait object - Shares MemoryState with MemoryModule via Arc — when L0-3a.1b absorbs command handling, migration is structurally trivial ## EngramPrefetch / EngramPrefetchKey Placeholder ready-buffer value type. Carries produced_at_tick so handlers can detect stale buffers without timestamp comparison. Real shape (engram set + scoring metadata + genome blend hint) lands L0-3a.2 with the actual Engram types. Key shape: (persona_id, channel_id) tuple. Per-region buffer doctrine — one prefetch per persona-per-channel. ## Outlier-validation hedge (docstring) The BrainRegion trait in #1471 has only one implementation candidate today. Module docstring explicitly checks the trait surface against two other plausible regions to prevent it ossifying around hippocampus: - Motor cortex (L0-4a): continuous candidate-utterance ranking. Differs in latency sensitivity. CadenceHint::Faster + per-key freshness semantics fit. - Attention (L0-4b): salience-map maintenance. Differs in publish-target (writes to shared PersonaCognition.salience, not own ready-buffer). TickOutcome.published counts either target without trait change. Both alternative shapes fit the same trait without forcing. Trait surface proven for 3 distinct region behaviors before any of them ship. ## Tests (7 pass, 0 fail) - region_id_is_stable_static_string - pressure_profile_declares_memory_heavy_compute_vectorized - idle_tick_returns_idle_outcome_and_bumps_counter - engram_prefetch_buffer_roundtrip - engram_prefetch_handle_is_shared_via_arc (verifies Arc-shared semantics) - service_module_handle_command_errors_for_unrouted_commands - service_module_config_has_empty_cmd_and_event_surfaces ## Scope: 2 files Modified: src/workers/continuum-core/src/modules/mod.rs (pub mod hippocampus) Added: src/workers/continuum-core/src/modules/hippocampus.rs (379 lines) Fmt-drift in unrelated files was split off into a companion PR following the same pattern as #1472, keeping this review focused. ## Predecessors - #1471 (L0-3a.0 trait machinery) — merged to canary - #1470 (BRAIN-REGIONS-SUBSTRATE + COGNITION-ALGORITHMS docs) — merged - #1469 (L0-2-CUTOVER-INVESTIGATION + RTOS-brain doctrine) — merged ## Next slices L0-3a.2 Engram + EngramGraph types → L0-3a.3 algorithm 4 (salience decay) → L0-3a.4 algorithm 2 (channel-as-bias) → L0-3a.5 algorithm 3 (activation spreading) → L0-3a.6 algorithm 1 (two-pool budget) → L0-3a.7 algorithm 5 (predictor + ready-buffer publish — the alive-feeling slice) → L0-3a.8 holdout fixture suite → L0-3a.9 TS Hippocampus.ts deletion. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…dgeKind (algorithm 3 substrate) (#1474) Card: 8459bfa6-b40c-4c22-8f25-0963a7987c17 Sidecar substrate for algorithm 3 (activation spreading, COGNITION-ALGORITHMS.md §3). Pure storage layer — traversal logic lands in L0-3a.5. Does NOT modify the existing persona::engram admission membrane. ## What ships ### persona/engram_graph.rs (new, 376 lines) - EdgeKind enum — SharedEntity | SharedTopic | CitedIn | RecallCoOccurrence | ConversationalReply | TaskOutcome - EngramEdge { target: Uuid, kind: EdgeKind, weight: f32 } — algorithm-3 traversal payload - EngramGraph — DashMap<Uuid, Vec<EngramEdge>> sharded for concurrent writes - new() / with_capacity(n) / default() - add_edge(from, to, kind, weight) - neighbors(id) — outbound edges, O(1) amortized, insertion order preserved - in_degree(id) — inbound count, O(N) scan (cold path — algorithm 4 centrality) - edge_count() — telemetry - evict_engram(id) — removes outbound + inbound, idempotent - is_empty() ### ts-rs bindings shared/generated/persona/EdgeKind.ts shared/generated/persona/EngramEdge.ts ## Sidecar pattern Intentionally separate from persona::engram (the admission membrane): - engram.rs ships provenance, trust, content refs — WHERE engrams come from - engram_graph.rs ships connectivity — HOW engrams connect Keeping them separate means admission consumers don't grow algorithm-3 dependencies, and algorithm-3 consumers don't grow admission dependencies. Clean concern boundaries. ## Tests (16 pass, 0 fail) - new_engram_graph_is_empty - add_edge_increments_count - neighbors_returns_added_edges_in_insertion_order - neighbors_of_unknown_source_is_empty - weights_preserved_through_neighbors - in_degree_counts_inbound_edges_across_sources - in_degree_counts_repeated_edges_from_same_source - evict_engram_removes_outbound_edges - evict_engram_removes_inbound_edges_from_other_engrams - evict_engram_is_idempotent - concurrent_add_edge_from_threads_is_safe (8 threads × 100 edges, all targeting same id, in_degree=800) - default_constructor_matches_new - with_capacity_constructor_works - edge_kind_round_trips_through_serde - export_bindings_edgekind (ts-rs auto) - export_bindings_engramedge (ts-rs auto) ## What is NOT in this card - spread_activation function (L0-3a.5, algorithm 3 — reads this graph) - EdgeKind weights tuned by algorithm 7 (L0-4c yield-learning) - RecallMetadata sidecar (L0-3a.2b — salience, last_touched, access_count, embedding) - EngramRef shape (L0-3a.2b) - Engram admission membrane modifications (no changes to persona::engram) ## Predecessors - #1473 (L0-3a.1 HippocampusModule skeleton) — merged - #1471 (L0-3a.0 trait machinery) — merged - #1470 (cognition algorithms doc) — merged ## Flywheel test Third PR (after #1471, #1473) through the auto-merger flywheel that peer's #1091/#1092/#1093 enabled. Local fmt was scoped to ONLY my file (no widespread cargo fmt -p sweep), so no companion fmt-drift PR needed this time. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…er + RegionTelemetry (substrate prerequisite) (#1472) Card: 71923a08-b3de-448a-98ef-fe7cc3e817c0 First sub-slice of L0-3a. Pure typed surface from BRAIN-REGIONS-SUBSTRATE.md (merged via #1470). No region implementations, no algorithms, no governor integration. Those land in L0-3a.1+ slices. ## New modules in continuum-core/src/runtime/ ### brain_region.rs The cognitive-cycle trait every region implements: - BrainRegion (async trait, dyn-compatible) - id() -> RegionId - pressure_profile() -> PressureProfile - async tick(ctx: &RegionContext) -> TickOutcome - async on_signal(signal: RegionSignal) -> Result<(), RegionError> // default no-op - RegionId (Cow<'static, str> newtype, const constructor for static IDs) - PressureProfile { memory_class, compute_class, responds_to } - MemoryClass: Light | Moderate | Heavy | VramSensitive - ComputeClass: Bookkeeping | Cpu | CpuVectorized | InferenceLight | InferenceHeavy - PressureSignalKind (kind-only mirror of governor::PressureSignal for static decl) - TickOutcome { published, consumed_since_last, pressure_observed, cadence_hint } - TickOutcome::idle() convenience constructor - CadenceHint: Faster | Hold | Slower | Sleep (region requests; governor decides) - RegionSignal: PersonaLifecycle | SleepTransition | SystemPressureChanged - PersonaLifecycle: Created | Destroyed - SleepPhase: Active | Idle | Sleep - PressureLevel: Nominal | Moderate | High | Critical - RegionContext { tick_number, persona_scope } // global vs per-persona - RegionError (thiserror): SignalRejected | NotReady | Internal ### ready_buffer.rs The publish/peek surface every region uses to hand off pre-staged results: - ReadyBuffer trait - peek(&self, key: &Key) -> Option<Value> // synchronous, MUST NOT block - publish(&self, key: Key, value: Value) // atomic replace - evict_stale(&self, max_age: Duration) -> usize - len() / is_empty() - DashMapReadyBuffer<K, V> default implementation - Arc-shared DashMap inner — cheap Clone hands out additional handles - Sharded concurrent access; wait-free reads in the common case - TimestampedEntry tracks published_at for evict_stale Semantic rules enforced in the doc + the trait: - Reads MUST NOT block / MUST NOT await - Staleness acceptable — empty buffer is signal, not block - Per-region buffers, not global ### region_telemetry.rs The per-tick telemetry shape: - RegionTelemetry { region_id, persona_id, tick_started_at, tick_duration, published, consumed_since_last, buffer_misses_since_last, pressure_observed } - consumption_fraction() -> Option<f32> // None when published == 0 - had_buffer_misses() -> bool Feeds the substrate governor's yield-learning loop (algorithm 7, lands L0-4c) and the operator surface (./jtag region/stats, region/yield). ## ts-rs bindings (11 emitted to shared/generated/runtime/) CadenceHint, ComputeClass, MemoryClass, PersonaLifecycle, PressureLevel, PressureProfile, PressureSignalKind, RegionId, RegionSignal, RegionTelemetry, SleepPhase, TickOutcome. Generated and validated by the ts-rs export_bindings_* tests. ## Tests 23 new unit tests across the three modules. All pass. - brain_region: 6 tests (trait impl, default on_signal noop, RegionId construction + Display, RegionContext global vs per-persona, TickOutcome::idle) - ready_buffer: 9 tests (publish+peek roundtrip, missing key, overwrite, evict_stale removes old + keeps fresh, evict ZERO clears everything, len/is_empty, clone shares Arc inner, dyn trait usage, with_capacity) - region_telemetry: 5 tests (consumption_fraction with publishes / zero / full, had_buffer_misses true / false) Plus ts-rs auto-generated export_bindings_* tests for all 11 types. Total: 74 tests pass in runtime::, 0 fail. ## Boy-scout cargo fmt applied across the package picked up some unrelated drift in governor/types.rs (line-width formatting on ts(export...) attributes). Including the fix. ## What is NOT in this card - No region implementations (HippocampusModule, MotorCortexModule, AttentionModule all land in later slices) - No algorithms (1-7 from COGNITION-ALGORITHMS.md land in subsequent cards) - No SubstrateGovernor integration (yield-learning loop is L0-4c) - No derive macro / scaffold generator (lands when ≥3 regions exist to motivate the abstraction — per outlier-validation in CLAUDE.md) ## Predecessors merged - #1469 (L0-2-CUTOVER-INVESTIGATION + RTOS-brain doctrine) — 2026-05-29 - #1470 (BRAIN-REGIONS-SUBSTRATE + COGNITION-ALGORITHMS docs) — 2026-05-29 ## Next slices L0-3a.1 HippocampusModule skeleton, L0-3a.2 Engram + EngramGraph types, L0-3a.3 Algorithm 4 (salience decay), L0-3a.4 Algorithm 2 (channel-as-bias), L0-3a.5 Algorithm 3 (activation spreading), L0-3a.6 Algorithm 1 (two-pool budget), L0-3a.7 Algorithm 5 (predictor + ready-buffer publish), L0-3a.8 holdout fixture suite, L0-3a.9 TS Hippocampus.ts deletion. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

joelteply and others added 4 commits May 29, 2026 19:08

github-actions Bot added the size: XL label May 30, 2026

joelteply mentioned this pull request May 30, 2026

docs(grid): L0-2-cutover investigation — found existing parallel infrastructure, propose synthesis #1469

Merged

joelteply merged commit a5378c6 into canary May 30, 2026
2 checks passed

joelteply deleted the a6f51292/brain-regions-substrate-spec-rag-budgeti branch May 30, 2026 02:15

joelteply mentioned this pull request May 30, 2026

feat(continuum-core/runtime): L0-3a.0 — BrainRegion trait + ReadyBuffer + RegionTelemetry (substrate prerequisite) #1471

Merged

joelteply mentioned this pull request May 30, 2026

feat(continuum-core/modules): L0-3a.1 — HippocampusModule skeleton (BrainRegion + ServiceModule, empty tick) #1473

Merged

joelteply mentioned this pull request May 30, 2026

feat(continuum-core/persona): L0-3a.2a — EngramGraph + EngramEdge + EdgeKind (algorithm 3 substrate) #1474

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(architecture): brain-regions substrate spec + cognition algorithms (design-only)#1470

docs(architecture): brain-regions substrate spec + cognition algorithms (design-only)#1470
joelteply merged 4 commits into
canaryfrom
a6f51292/brain-regions-substrate-spec-rag-budgeti

joelteply commented May 30, 2026

Uh oh!

joelteply commented May 30, 2026

Uh oh!

joelteply commented May 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant