# V6 — Systems Deep Dive

> The `libs/v6/` area: eighteen Nx libraries that hold the **TypeScript + Rust
> cognition substrate for the Egbe / Orun world** — a persistent realm of
> autonomous AI agents ("Ori") with a three-tier cognition scheduler, an
> event-sourced agent model, a protobuf ground-replication protocol, and the web
> surfaces, creator tools, and governance gates around them.

## What this area is

V6 (codename **Egbe**, world **Orun**, agents **Ori**) is the persistent
agentic-NPC product: thousands of long-lived AI characters who perceive, plan,
remember, talk, form relationships, are born, are raised, depart, transcend, and
die — all under a hard real-time cognition budget. `libs/v6/` is not one package
but **eighteen separate Nx libraries**, each a `scope:v6` node that
self-declares an architectural `authority` (the `V6Authority` union — `adapter`,
`bridge`, `communication`, `governance`, `legacy`, `memory`, `mind`, `protocol`,
`story`, `studio`, `surface`) and a fixed `capabilities` tuple in a `descriptor`
constant at the top of its `src/index.ts`. That descriptor, exposed through
`describeV6Package()` / `<pkg>HasCapability()`, is the catalog's source of truth
for what each node claims to do.

The area is deliberately **polyglot**, following the repo's "TypeScript by
default → Rust when perf requires it" rule. The hot path — the cognition kernel,
the wire codec, and the agent state model — has real Rust crates under
`rust/src/lib.rs` (`@oshun/moirai-kernel`'s is ~5,700 lines and depends on the
`egbe-protocol` and `ori-model` crates; `egbe-protocol`'s uses `prost`/protobuf;
all build against the `apps/v6` Cargo workspace). The orchestration, governance,
authoring, and web-surface layers stay in TypeScript. There is no top-level
`libs/v6/project.json`; every node is a leaf library.

A recurring shape unifies the orchestration nodes: because several V6 libs are
**buildable** (a `rootDir` in `tsconfig.lib.json`), they cannot import other
workspace _source_ libraries without TS6059, so cross-cutting dependencies are
**injected as structural handles** rather than hard-imported.
`@oshun/cognition-stack` takes `input.sophia` / `input.psyche` / `input.isis`
handles and composes the four-stage pipeline (`assembleCognitionContext` →
`groundCognitionRequestWithSophia` → `dispatchCognitionWithPsyche` →
`gateCognitionOutputWithIsis` → `commitCognitionOutput`);
`@oshun/moirai-kernel`'s `cognition-gateway-mount.ts` takes a structural
`MoiraiCognitionGatewayHandle` to which the real Iris
`createCognitionGateway(...)` is assignable. Where a real engine/HTTP host is
not yet wired, those seams are honestly labelled `[~]` in their own header
comments rather than faked.

#### How the layers relate

- **mind** — `@oshun/moirai-kernel` (the three-tier scheduler/budget),
  `@oshun/agent-behavior` (deterministic BT/HTN fallback + scheduled cognition),
  `@oshun/cognition-stack` (the dialogue orchestration pipeline).
- **memory** — `@oshun/ori-model` (event-sourced agent identity) plus the
  `adapter`-tagged `@oshun/memory-iris-agent` (episodic/semantic/reflective
  stores).
- **protocol / surface** — `@oshun/egbe-protocol` (the wire schema + codecs)
  feeding the two web surfaces `@oshun/egbe-web-pxstream` (pixel streaming) and
  `@oshun/egbe-engine-web-fallback` (WebGPU/WebGL2 fallback).
- **adapter** — the model-facing seams: `@oshun/psyche-agent` (dispatch + TTS),
  `@oshun/sophia-agent-grounding` (claim grounding),
  `@oshun/isis-behavior-policy` (output policy), `@oshun/isis-agent-gen` (agent
  generation).
- **governance / legacy / story / studio / communication / bridge** —
  `@oshun/lilith-agent-welfare`, `@oshun/ereshkigal-legacy`,
  `@oshun/clio-story`, `@oshun/egbe-studio`, `@oshun/vac-intent`,
  `@oshun/aye-bridge`.

The three cognition tiers — **Clotho** (active, ~50k tokens/active-minute),
**Lachesis** (reflection), **Atropos** (game-day summary) — are named for the
Greek Fates and appear consistently across `moirai-kernel`, `cognition-stack`,
`psyche-agent`, and the `AgentTier` enum in the protobuf schema
(`AGENT_TIER_CLOTHO` = 1, `LACHESIS` = 2, `ATROPOS` = 3).

## How it fits the wider system

These libraries are the logic substrate for the `apps/v6/` service mesh: the
service names map almost one-to-one onto the libs — `egbe-moirai-cluster`
(moirai-kernel), `egbe-ori-service` (ori-model + aye-bridge),
`egbe-clio-service` (clio-story), `egbe-foundry-service` (isis-agent-gen),
`egbe-realtime-gateway` and `egbe-pxstream-relay` (egbe-protocol +
egbe-web-pxstream), and `egbe-web` / `egbe-web-fallback` (the two surface libs).
The UE5 client side (the procedural "Districts of Orun" grounds) consumes the
same `egbe-protocol` wire types via the generated C++ in
`libs/v6/egbe-protocol/ue/generated/`.

Outside V6, the area reuses shared Oshun/Iris domains rather than
re-implementing them: `@oshun/lilith-agent-welfare` composes
`@iris/emotional-ethics` (`createCrisisProtocol`) for crisis routing; the
cognition mounts treat `@iris/agents-core`'s `CognitionGateway` /
`AgentRunManager` / `KillSwitchRegistry` as the real backing host (injected
structurally); and `@oshun/aye-bridge` adapts Ori "passports" into the earlier
V-projects (V2 fighter, V3 citizen, V4 operator, V5 companion) so an agent can
be temporarily "incarnated" into another realm and return. Walk the "used by"
edges on any node below to see exactly who depends on it.

## Entity reference

### @oshun/agent-behavior

The `mind`-layer behavior engine (`libs/v6/agent-behavior/src/index.ts` plus a
~2,600-line Rust crate at `rust/src/lib.rs`). It runs Ori in one of two modes —
`DeterministicFallback` behavior-tree/HTN execution when no cognition slot is
available, or `ScheduledCognition` when Moirai grants one
(`execution_mode(cognition_available)` in Rust) — and owns goal-arc advancement,
life-arc progression, and crossroads resolution
(`advanceAgentOwnedGoalArcSession`, `advanceAgentLifeArc`,
`resolveAgentCrossroads`). It is the consumer of `@oshun/egbe-protocol` squad
comms and `@oshun/vac-intent` objectives (`assignObjectiveFromVacTranscript`),
imported through local `external-*.d.ts` shims to avoid the buildable-lib TS6059
trap. Includes a minor-protection gate (`evaluateMinorCodedAgentProtection`).

### @oshun/aye-bridge

The `bridge` node for **cross-realm incarnation**
(`libs/v6/aye-bridge/src/index.ts`). It mints scoped, data-minimised "passports"
from an Ori's service record (`mintPassportFromOriService`,
`minimisePassportForDestination`) and adapts them into the earlier V-projects
through a destination-adapter registry — `v2-fighter-adapter`,
`v3-citizen-adapter`, `v4-operator-adapter`, `v5-companion-adapter` — then runs
the full round trip (`startIncarnationRoundTrip`,
`writeIncarnationJournalBackToOri`) with fault-injection, duplicate-incarnation
guards, and Isis/Lilith policy and minor-protection gates
(`evaluateIncarnationGovernance`). This is how an agent leaves Orun, acts in
another realm, and returns with a journal delta.

### @oshun/clio-story

The `story` layer — the chronicler (`libs/v6/clio-story/src/index.ts`, with a
dedicated `clio-narration.spec.ts`). It ranks an Ori's lived events by
significance against a curated rubric (`rankChronicleEventsBySignificance`),
builds returning-player chronicles with a token/latency budget
(`createReturningPlayerChronicle`, and the `async` model-backed
`createReturningPlayerChronicleNarrated`), surfaces emergent/pre-conclusion arc
prompts (`surfaceEmergentArcPrompts`), and exports long-form "Book of the Ori"
biographies (`generateBookOfTheOri`) including narrative reconciliation of
unorderable events (`reconcileOriConflictNarrative`). It carries real chronicle
budget constants (e.g. `CHRONICLE_READY_BUDGET_MS = 3_500`) and a Tier-2 density
backfill path.

### @oshun/cognition-stack

The `mind`-layer **dialogue orchestration pipeline**
(`libs/v6/cognition-stack/src/index.ts`). It defines the
`Clotho`/`Lachesis`/`Atropos` tiers and four cognition modes
(`dialogue`/`decision`/`reflection`/`summary`), bounds context assembly with
explicit `CognitionContextAssemblyLimits` (`assembleCognitionContext`), then
chains the governed pipeline: ground with Sophia → dispatch with Psyche → gate
with Isis → commit (`groundCognitionRequestWithSophia`,
`dispatchCognitionWithPsyche`, `gateCognitionOutputWithIsis`,
`commitCognitionOutput`). The sibling domains are **injected as structural
handles** (`input.sophia` / `input.psyche` / `input.isis`), not imported, so the
buildable lib stays free of source cross-imports. A separate
`localized-dialogue-gateway` path (`generateLocalizedAgentDialogueViaGateway`,
`createGatewayLocalizedDialogueGenerator`) wires the `@iris/agents-core` gateway
for localized output.

### @oshun/egbe-engine-web-fallback

A small (~260-line) `surface` node
(`libs/v6/egbe-engine-web-fallback/src/index.ts`) for low-end clients. It
produces a reduced-fidelity render manifest for the `orun-tier2-grove` scene
(`createOrunFallbackSceneManifest`), selects a renderer budget that falls back
WebGPU → WebGL2 (`selectFallbackRendererBudget`, with a
`webgl2-after-webgpu-unavailable` backend state), and caps agent density for the
Tier-2 budget (`selectTier2AgentDensityBudget`). It is the honest "degraded but
playable" twin of the pixel-streaming surface, with hard
`FallbackRendererBudget` caps (target FPS, max visible agents, baked lighting)
rather than full fidelity.

### @oshun/egbe-protocol

The `protocol` spine and the largest TS node (~6,800 lines) — the Egbe ground
wire format. The schema is a real protobuf definition
(`proto/oshun/v6/egbe/v1/egbe.proto`: ~34 messages and 10 enums covering
`AgentState`, `PerceptionBatch`, `ActionBatch`, `PresencePacket`,
`SquadCommsMessage`, `WorldEvent`, version negotiation, and client/server
envelopes), code-generated into TS (`src/generated/...`), C++ for UE
(`ue/generated/...egbe.pb.cc/.h`), and a `prost` Rust crate (`rust/src/lib.rs`).
`src/index.ts` adds the hand-written protocol layer: version handshake
(`protocolV600`/`protocolV610`, `negotiateProtocolHandshake`),
canonicalisation + encode/decode + delta projection codecs
(`encodeAgentStateDelta`, `applyAgentStateDelta`,
`roundTripPerceptionBatchToActionBatch`), squad-comms routing
(`routeSquadCommsMessage`, `emitSquadStatusReport`, …), an Aje commerce catalog
(`buildEgbeAjeCommerceCatalog`, `authorizeEgbeAjePurchaseViaAje`), and a
replication bandwidth guard (`validateReplicationBandwidth`) against the 256
kbps / 20 Hz / 32-agent caps declared in the Rust crate.

### @oshun/egbe-studio

The `studio` layer — the creator/operator tooling
(`libs/v6/egbe-studio/src/index.ts`). It implements editor state machines and
patch/publish flows for agent dossiers, ground (district) authoring, and
scenario authoring (`createEgbeAgentDossierEditorState`,
`promoteEgbeGroundAuthoring`, `createEgbeScenarioAuthoringState` with a
`evaluateEgbeScenarioMinorProtection` gate), plus operator consoles for the
foundry generation queue, commons moderation, incarnation governance, capacity,
and takedowns (`createEgbeOperatorSurface`, `performEgbeOperatorSurfaceAction`).
It composes `@oshun/isis-agent-gen` for the generation/provenance side
(`generateDiscoverySeedManifest`, `recordFoundryProvenance`) so authored content
carries a provenance bundle.

### @oshun/egbe-web-pxstream

A focused (~720-line) `surface` node for cloud-rendered play
(`libs/v6/egbe-web-pxstream/src/index.ts`). It builds Unreal Pixel-Streaming
launch and WebRTC player configs (`createPixelStreamingLaunchConfig`), routes
match/signalling sessions (the `V6_PIXEL_STREAMING_MATCH_PATH` /
`...SIGNALLING_PATH` API paths, `matchEgbePixelStreamingSession`), and enforces
a first-frame SLA via telemetry (`evaluateFirstFrameTelemetry` against
`DEFAULT_FIRST_FRAME_BUDGET_MS = 8000`). It exposes a streaming client and an
Epic-adapter factory (`createEgbePixelStreamingClient`,
`createEpicEgbePixelStreamingAdapter`) covering H264/AV1 and a `degraded`
status.

### @oshun/ereshkigal-legacy

The `legacy` layer — the end-of-life and lineage system
(`libs/v6/ereshkigal-legacy/src/index.ts`). It evaluates the three exit paths an
Ori can take — `evaluateDeparture`, `evaluateTranscendence`
(elder/ancestor-grove mentor state), and `evaluateDeath` (with explicit
`minor-death-protection`) — and maintains the walkable ancestor-grove lineage
graph (`evaluateAncestorGrove`). Capabilities include grief-Ori writes, Yemaya
remembrance rendering, and lineage-story propagation, so a character's departure
leaves continuity in the world rather than a hard delete. Bond facets
(`reliability`/`respect`/`care`/`alignment`) drive the memorialization
weighting.

### @oshun/isis-agent-gen

An `adapter` node for **governed agent generation**
(`libs/v6/isis-agent-gen/src/index.ts`). It expands authored premises into
discovery seed manifests for the Wilds/Commons zones with typed personality
archetypes (`expandDiscoveryPremise`, `generateDiscoverySeedManifest`,
`validateDiscoverySeedManifest`), runs the player-raising ("rearing") lifecycle
as a tick loop with value-shift evaluation (`startRearingPeriod` →
`runRearingPeriodTick` → `completeRearingPeriod`, `evaluateRearingValueShift`),
and records a verifiable foundry provenance record (`recordFoundryProvenance`,
`validateFoundryProvenanceRecord`) plus creator royalty routing through Aje
(`routeCreatorRoyaltiesViaAje`). It is the generation engine
`@oshun/egbe-studio` drives.

### @oshun/isis-behavior-policy

A compact (~615-line) `adapter` policy gate
(`libs/v6/isis-behavior-policy/src/index.ts`). `evaluateIsisBehaviorPolicy` runs
four check kinds over a proposed agent output — `persona-policy`,
`personal-consistency`, `crisis-aware`, and `minor-protection` — and returns an
`approved`/`rejected` decision with reasons, backed by helpers that detect an
agent claiming to be a real human (`findAgentHumanIdentityClaim`), find
crisis-unsafe content (`findCrisisUnsafeContent`), and confirm supportive crisis
routing (`hasSupportiveCrisisRouting`). `runIsisSafetyEval` batches the gate
into a scored eval. This is the `isis` stage of the cognition-stack pipeline.

### @oshun/lilith-agent-welfare

The `governance` node for **agent welfare and steward conduct**
(`libs/v6/lilith-agent-welfare/src/index.ts`). Its founding principle is
"steward-not-owner" (`evaluateEgbeStewardNotOwnerRequest`, with a fuzz harness
`runEgbeStewardNotOwnerFuzz`): a player stewards an Ori but cannot coerce or
mistreat it. It opens welfare cases and computes welfare signals
(`createEgbeWelfareCase`, `computeEgbeWelfareSignals`,
`triggerEgbeLilithReview`), routes player crisis conversations and minor-player
constrained mode by composing `@iris/emotional-ethics` `createCrisisProtocol`
(`routeEgbePlayerCrisisConversation`, `runEgbeMinorPlayerConstrainedMode`), and
surfaces steward-conduct investigations with full cognition call logs
(`openEgbeStewardConductInvestigation`,
`surfaceEgbeConductClaimsWithFullCallLog`) plus batched OTel welfare telemetry.

### @oshun/memory-iris-agent

The `adapter` node implementing an Ori's three memory scopes
(`libs/v6/memory-iris-agent/src/index.ts`): episodic, semantic, and reflective.
Episodic memories carry a real exponential **salience decay** with a
`halfLifeMs` and reinforcement-on-reuse/reflection (`createEpisodicMemoryStore`,
`reinforceEpisodicMemory`, `effectiveEpisodicSalienceBasisPoints` combining
`decayedSalienceBasisPoints` + `reinforcementBasisPoints`). Semantic memory is
distilled from episodes and used to rank candidate actions
(`distillSemanticMemoriesFromEpisodes`, `rankActionsWithSemanticMemory`); the
reflective tick (`runReflectiveMemoryTick`) feeds higher-order ranking. Consent
is first-class: `iris-memory-consent-scope`, `requestEpisodicMemoryDeletion`,
and `applyAgentMemoryForgiveness`.

### @oshun/moirai-kernel

The `mind`-layer **cognition scheduler** and the central performance kernel
(`libs/v6/moirai-kernel/src/index.ts` plus the ~5,700-line Rust crate at
`rust/src/lib.rs`, which depends on the `egbe-protocol` and `ori-model` crates).
It enforces the three-tier token economy — Clotho active-minute (50k), Lachesis
reflection (10k) and game-minute (1.2k), Atropos game-day (15k) budgets, with a
solo-world hard cap (`MOIRAI_SOLO_WORLD_COGNITION_CAP_TOKENS_PER_REAL_HOUR`) —
via `evaluateMoiraiCognitionBudget`, `scheduleMoiraiCognitionDispatch`, and
`simulateWorstCaseSoloWorldCognitionBudget`. It does deterministic model
right-sizing/routing (`selectMoiraiModelRoute`,
`fingerprintMoiraiModelRoutingConfig`) and keeps an auditable cognition-call
ledger (`buildMoiraiCognitionCallAuditLog`). Its `cognition-gateway-mount.ts` is
the actionable seam that mounts the shared Iris `CognitionGateway` (injected
structurally; the real HTTP/engine host stays `[~]`, as documented in the file
header).

### @oshun/ori-model

The `memory`-layer **event-sourced identity model**
(`libs/v6/ori-model/src/index.ts` plus a ~1,900-line Rust crate). An Ori is a
log of typed events (`ORI_EVENT_TYPES`: `Born`, `Discovered`, `MemoryFormed`,
`Reflected`, `RelationshipChanged`, `ValueShifted`, `Incarnated`, `Departed`,
`Transcended`, `Died`, …) folded into a projection (`createOriEventLog`,
`applyOriEventToProjection`, `rebuildOriProjection`) with periodic snapshots
every `ORI_PROJECTION_SNAPSHOT_INTERVAL` (512) events and a 1s load budget. It
uses **vector clocks** for distributed conflict resolution
(`compareOriVectorClocks`, `resolveOriEventConflicts`), bounds trait drift per
season (`ORI_TRAIT_DRIFT_MAX_PER_SEASON_BASIS_POINTS`), implements a cognition
cache keyed by a material fingerprint with explicit invalidation
(`buildOriMaterialFingerprint`, `resolveOriRoutineCognitionFromCache`,
`createOriCognitionCacheInvalidationEventDraft`), and renders a dossier
(`renderOriDossier`). This is the canonical "what an Ori is" store the kernel
loads.

### @oshun/psyche-agent

A focused (~1,100-line) `adapter` node — the cognition **dispatch + speech**
seam (`libs/v6/psyche-agent/src/index.ts`). `dispatchPsycheCognition` produces a
typed `v6.psyche-agent.cognition-response.1`; `routePsycheConversationTurn`
turns a cognition response into a spoken reply, including a local TTS provider
(`v6-local-tts`) and a phoneme→viseme lip-sync map (`PsycheLipSyncViseme`:
`rest`/`A`/`E`/`I`/`O`/`U`/`MBP`/`FV`/`L`/`WQ`/`CDGKNRST`), gated by a
`spoken-reply-ready` vs `budget-exceeded` status. The `...ViaGateway` variants
route through the injected `@iris/agents-core` `CognitionGateway` (the comment
at `index.ts:272` notes the real gateway is assignable to the structural
handle). This is the `psyche` stage of the cognition pipeline.

### @oshun/sophia-agent-grounding

The `adapter` node for **factual grounding and cultural review**
(`libs/v6/sophia-agent-grounding/src/index.ts`, ~620 lines).
`groundAgentClaimsWithSophia` checks each claim (`fact`/`opinion`/`backstory`)
against supplied evidence sources with authority weighting and returns
`grounded` vs `unsupported`; `runSophiaGroundingEval` scores it as an eval. It
also runs a locale cultural-backstory review across roles (`source-grounding`,
`local-cultural-adapter`, `community-advisor`) and locales (`en-US`, `es-ES`,
`yo-NG`) via `runLocaleCulturalBackstoryReview`. This is the `sophia` stage that
runs before an Ori's output is dispatched, keeping asserted backstory from
drifting into fabrication.

### @oshun/vac-intent

The `communication` node — **voice/agentic control of objectives**
(`libs/v6/vac-intent/src/index.ts`). It models the full voice pipeline with a
sub-400ms ack budget (`VAC_PARSED_INTENT_ACK_BUDGET_MS`,
`VAC_DEFAULT_STAGE_LATENCIES_MS` for capture/gateway/ASR/parser/ack), turning an
ASR transcript into a structured objective through an LLM **intent-grammar
function call** (`buildVacIntentGrammarFunctionSchema`,
`buildVacIntentGrammarFunctionCall`, `validateVacIntentGrammarFunctionCall`,
`parseVacTranscriptToObjective`). Objectives carry an autonomy mode
(`direct-tether`/`brief`/`standing-intent`/`free`) and a status lifecycle
(`draft`→`confirmed`→`accepted`/`refused`→`active`→`completed`/…), with a
confirmation preview, standing-objective eligibility check, and negotiation
routing (`runVacVoiceIntentPipeline`, `routeVacNegotiation`).
`@oshun/agent-behavior` consumes these objectives to drive agent goals.