docs(arch): SHARED-COGNITION.md — shared objective analysis + LoRA-rendered specialty per persona

[joelteply]

Summary

Architecture memo for the work Joel + memento are about to implement together. Doc-only — no code changes. Sets the contract before implementation begins.

The cognitive operation behind a persona response is two distinct things fused into one expensive call today:

1. Objective analysis — what the message means, what RAG context matters, what would any thoughtful agent observe. Same answer regardless of who's responding.
2. Specialty-rendered response — given that objective picture, what does this persona, with their particular trained expertise (LoRA adapter), contribute?

Currently each of N personas independently does both. Result Joel saw tonight: 6-minute end-to-end latency on a chat message, with each persona spending ~36s of inference (most of it in hidden think-tokens deriving the same objective foundation) before contributing their voice-flavored slice.

The fix: split the operation. One shared analysis pass produces the objective ground floor. Each persona's render pass runs through their LoRA-adapted genome to contribute their specialty without rebuilding the foundation.

Two phases

• Phase A — shared analysis + relevance-filtered renders. Immediate ship; slots into existing PRG without restructuring the cognition loop.
• Phase B — streaming collaborative reasoning. Personas see each other's render in flight, build on / disagree / stay silent based on whether their specialty adds genuine signal. Real meeting-of-experts behavior.

What this enables that we can't do today

• Genuine specialty differentiation in production — distinct LoRA weights, not distinct prompts.
• Honest "I have nothing to add" — silence becomes the natural state via PressureBroker-driven adapter eviction.
• Linear-cost adding personas — Pantheon rooms with 14 specialists become tractable.
• Real meeting metaphor — debate, building-on, silence as first-class behaviors.

Composes for free with already-shipped infrastructure

• `ChatCoordinationStream` — adds `SharedAnalysis` as a new thought type
• `GenomePagingEngine` (feat(paging): GenomePagingEngine broker eviction lever (Phase 3a) #934) — activates each responder's specialty adapter
• `PressureBroker` (feat(paging): PressureBroker scaffolding (Phase 7a) #932) — relevance-driven eviction enforces "shut up when you're not the right expert"
• `EmbeddingPool` (feat(paging): EmbeddingCache → PagedResourcePool (Phase 2 — fixes 0/64 hit rate) #933) — shared analysis hits the cache once
• Forge alloy — LoRAs become load-bearing in production, not just training

Migration ladder

A.1 → A.2 → A.3 → A.4 → B.1 → B.2 → B.3 (see doc for details). 7 small ships.

Test plan

• Joel + memento read + nitpick the contract before any code lands
• Phase A.1 (`SharedAnalysisService` scaffolding) is the first PR; merge gate is tests proving stable shape + cache hit on repeated input
• Each subsequent phase has its own measurable acceptance gate (latency drop, distinct outputs per LoRA, silence-when-irrelevant)

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a new architecture memo describing a planned “shared cognition” pipeline that separates a single shared objective-analysis pass from per-persona LoRA specialty renders, with a phased migration plan (Phase A/B) intended to reduce multi-persona latency and enable relevance-driven silence.

Changes:

• Introduces docs/architecture/SHARED-COGNITION.md documenting the shared-analysis + per-persona render split.
• Describes Phase A (non-streaming) and Phase B (streaming collaborative reasoning) rollouts with an explicit migration ladder and test gates.
• Maps the design onto existing infrastructure concepts (coordination stream, paging/pressure primitives, embedding cache).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

This table also uses a double leading pipe (|| ...), which creates an extra empty column in rendered Markdown. Switch to a single leading | in the header and rows so it renders as a 2-column table.

[Copilot]

The InferenceCoordinator implementation in-repo is a FIFO capacity guard (requestSlot(personaId, messageId, provider)) and does not currently expose/implement priority levels. This row reads like priorities already exist ("analysis is priority 0 ... renders priority 1"); consider rephrasing as a future extension or describing current FIFO behavior to avoid documenting a non-existent API.

Suggested change

	| `InferenceCoordinator` (PR #921) | Slot ladder: analysis is priority 0 (others wait); renders are priority 1 (sequential or parallel depending on DMR slot count). |
	| `InferenceCoordinator` (PR #921) | Provides the existing FIFO capacity guard for inference slot acquisition. Shared cognition can route the shared analysis pass and subsequent renders through that queue today; explicit analysis-first prioritization would be a future extension, not current `InferenceCoordinator` behavior. |

[Copilot]

The Phase A flow calls PRG.render(sharedAnalysis), but the migration ladder later proposes respondFromSharedAnalysis(sharedAnalysis, specialty) as the new PRG API. Consider standardizing on one name/signature in the doc to keep the contract unambiguous.

Suggested change

	- PRG.render(sharedAnalysis) ← short prompt, LoRA-rendered
	- PRG.respondFromSharedAnalysis(sharedAnalysis, persona.specialty)
	← short prompt, LoRA-rendered

[Copilot]

The markdown table header/rows use a double leading pipe (|| ...), which renders as an extra empty first column in GitHub Markdown. Use a single leading | for the header and each row so the table formats correctly.

[Copilot]

Section title "The compose with GenomePagingEngine + PressureBroker" is grammatically incorrect and reads like a typo. Consider renaming to "Composes with ..." or "Compose with ..." for clarity and consistency with later headings.

Suggested change

	### The compose with `GenomePagingEngine` + `PressureBroker`
	### Composes with `GenomePagingEngine` + `PressureBroker`

[Copilot]

The doc refers to GenomePagingEngine.activateSkill(...), but the Rust API is activate_skill(...) and the TypeScript-facing entrypoint appears to be PersonaGenome.activateSkill(...). Using the wrong symbol name here makes the contract harder to follow; please align the doc with the actual call site/API you expect to invoke.

Suggested change

	- **Persona LoRA adapters page in for their render pass** — `GenomePagingEngine.activateSkill(persona.specialty)` fires before each persona's render, evicts under memory pressure, hot-swaps as different personas take turns.
	- **Persona LoRA adapters page in for their render pass** — `PersonaGenome.activateSkill(persona.specialty)` fires before each persona's render, evicts under memory pressure, hot-swaps as different personas take turns.

[Copilot]

Same naming issue here: GenomePagingEngine.activateSkill(...) doesn’t match the Rust method name (activate_skill) and in TS the activation call is PersonaGenome.activateSkill. Update this step to use the correct symbol(s) so future implementers can map the doc to code quickly.

Suggested change

	- GenomePagingEngine.activateSkill(persona.specialty)
	- Activate the persona genome skill
	- TS: `PersonaGenome.activateSkill(persona.specialty)`
	- Rust: `activate_skill(persona.specialty)`

[Copilot]

This step also uses GenomePagingEngine.activateSkill(...); please standardize on the actual API name (Rust activate_skill and/or TS PersonaGenome.activateSkill) throughout the doc to avoid ambiguity about which layer owns activation.