# Psyche/Lilith learning map and pinned-code boundaries

Source revision: `1ceae52c7896a59ac74a4429d410f3218f0b91c6`. This is a partial
review for the [full continuation plan](../TODOS.md), not whole-domain teaching,
live media, authenticated policy enforcement or release acceptance.

## Learning sequence and evidence boundary

The fifteen-slide guide now separates stream admission, server-turn outcomes,
measurement targets, load decisions, capability fallback, runtime trigger
selection and upgrade recovery. Four focused slides were added for turn
outcomes, latency targets, runtime triggers and recovery. Ten existing
explanations were corrected or enriched. The subsequently requested composition
pilot also redesigns the shared member-day context as an optional journey with
an explicit return, skip path and continuity limits, in both Psyche/Lilith and
web/PWA. Persona policy, shell handoffs and asset release remain separate
responsibilities.

[Five reviewed assignments](../assignments/psyche-runtime-boundaries.json) bind
complete architecture units to their assembled slide hashes:

| Source unit                           | Lines   | Teaching home                                           |
| ------------------------------------- | ------- | ------------------------------------------------------- |
| Event taxonomy and gap-free stream    | 159–199 | `psyche-session-stream`                                 |
| Server-mediated turn-taking           | 200–222 | `psyche-turn-outcomes`, `psyche-lilith-worked`          |
| Latency budgets and thinking deadline | 223–249 | `psyche-latency-targets`, `psyche-latency-backpressure` |
| Backpressure                          | 250–268 | `psyche-latency-backpressure`                           |
| Fallback cascade                      | 269–287 | `psyche-fallback`, `psyche-runtime-fallback`            |

The architecture and feature pages for Psyche, Lilith policy and persona packs,
plus the assistant-experience and mentor-presence feature pages, have been read
in full. Full pinned implementation review covers `session-events.ts`,
`session-trace.ts`, `latency-dashboard.ts`, `backpressure.ts` and
`fallback-routing.ts` in `libs/oshun/embodiment-psyche/src/`.

`tools/presentations/tests/pinned-psyche-runtime.test.mjs` executes those exact
Git objects through TypeScript transpilation and a guarded VM. The event module
uses the actual pinned trace helper; the other modules have no runtime imports.
Forty-nine controlled tests pass, including all 64 supplied-signal subsets in
each of the three current modes against the authored priority-decision edges.
Each malformed selected signal throws rather than trying a valid lower signal;
invalid current-mode input throws before selection. The diagram's no-match,
valid and invalid outcomes remain distinct from executed consumer effects.
Transpilation is not a project typecheck; no socket, authenticated actor, clock
scheduler, device output, provider, persisted audit or underlying product
integration is exercised.

## Stream and server-turn corrections

- The union has 15 canonical V1, two server and 19 legacy event kinds. These are
  three families, not one fifteen-kind protocol.
- Event construction validates identity, sequence, timestamp, actor, payload and
  timing fields. Append independently checks session, trace, next sequence and
  nondecreasing event time; it does not call the event builder or full
  validator. Duplicate IDs and directly supplied malformed payloads/dates can
  pass append and fail explicit full validation.
- Full validation checks duplicate IDs and gap-free ordering, but does not
  require nonblank event IDs, align `lastUpdatedAt` with the last event, or
  enforce creation-before-first-event. A lifecycle event only requires two
  unequal state strings; it does not validate the lifecycle graph. These typed
  helpers are not a complete untrusted-JSON admission boundary.
- Readonly declarations do not freeze objects. Event payloads and appended
  events remain aliased; initial stream construction reuses the supplied event
  array. Correlation IDs and the derived 64-bit FNV-1a trace label are not
  authenticated signatures; any nonblank supplied trace ID is accepted.
- Start emits `turn-start` and enters active. End emits `turn-end` followed by
  `turn-complete`, clears the active turn and enters complete. A denied
  interruption emits one `interruption` event and advances sequence while
  leaving the turn active. Approval emits `interruption` then an interrupted
  `turn-end`, with no `turn-complete`, and enters interrupted.
- System-initiated barge-in sets approval and the system flag itself, using the
  supplied actor ID; it does not authenticate that the actor has a system role.
  The caller owns authorization. Starting after complete/interrupted is
  possible; ending again without a new start fails.
- The 180 ms partial-TTS fade is a default integer, not a maximum. Zero and
  10,000 ms are accepted; negative/fractional values are rejected. Turn ceiling
  is also event data, not a running timer. Approved interruption/end reject
  negative duration; denied interruption does not compute duration.
- Reducer results are not automatically appended. Media events can advance the
  stream sequence independently, requiring caller reconciliation. Media fade,
  stale-output cancellation, persistence and transport replay remain separate
  execution and verification work.

## Latency and pressure corrections

- Voice first-audio targets are 500/900/1500 ms at p50/p95/p99; first token is
  350/700 ms at p50/p95; avatar frame is 80 ms p50; ASR final text is 150 ms
  p50. Their timestamp pairs differ. Builders check finite, ordered endpoints
  but defer `observedAtMs` validation to sample admission.
- The default ring holds 256 samples and evicts by insertion order, not age or
  timestamp sorting. Percentiles use nearest rank within the selected kind.
  Empty samples produce zero percentiles and `ok`, with `sampleCount: 0`; this
  is not measured service success.
- The general budget assessor only reads round-trip and pipeline-total. A
  first-token breach can coexist with its overall `ok`. Focused metric checks
  breach strictly above target and warn strictly between 80 percent and the
  target; an exact avatar target can be `ok`. The separate SLO dashboard warns
  inclusively from 90 percent through the target, so the exact target is a
  warning there.
- Dashboard groups use region/provider/persona/kind. Impact is the maximum
  declared count per group, then summed across affected groups, not distinct
  people. Targets omitted for a kind give no breach. Per-kind custom target
  objects replace rather than merge the default percentile fields.
- Admission considers free session slots and the first saturated service;
  pending queue counts do not influence it. Paying/operator requests return
  `defer-lower-priority` under pressure without proving there is a victim. Other
  requests queue at a service bottleneck; at session capacity, standard members
  queue while preview/background are rejected.
- Shedding chooses oldest background then preview for text downgrade, then
  noncritical standard members for disconnect and critical standard members for
  handoff. Paying/operator sessions are excluded, so a target of zero may be
  unattainable. A downgrade is not itself removal of a running session.
- Load status and admission are separate calculations. An elevated status can
  recommend refusing preview while admission still admits it. Zero caps are
  treated as zero utilization by status but as capacity exhaustion by admission.
- Any nonhealthy provider enables both ASR and model throttles, even an avatar
  provider. Defaults are half-rate throttles, a 200 ms thinking deadline and
  text fallback at the longest degradation reaching 2500 ms. Severity alone does
  not trigger immediate fallback. The deadline clamps to at most 200;
  zero/invalid policy numbers restore defaults rather than disable a feature.
  These are returned instructions, not scheduled UI or provider effects.

## Fallback is several different functions

- Capability resolution chooses at or below the requested avatar/voice/text
  tier. Defaults resolve an avatar request to text because avatar permission and
  recording capability are absent. It checks categorical network type;
  `roundTripMs` is validated but unused in selection. Unknown network is not
  automatically rejected; 3g blocks avatar but permits voice, slow blocks both.
- Avatar eligibility checks avatar entitlement/backend/render/GPU/network, not
  microphone, playback, voice entitlement or voice backend. Thus it can return
  avatar while voice independently resolves to text, although the avatar
  renegotiation plan includes voice and TTS. Integrators must reconcile this
  seam; the probe is not a universal media or rights gate.
- Cascade stages carry notices and decline targets; they can describe an
  intermediate voice step even when voice is unavailable and the final target is
  text. They are not evidence that each intermediate session ran. The plan
  builder trusts the supplied resolution and can accept avatar for a requested
  text tier; only the capability resolver itself guarantees no upgrade.
- Runtime trigger priority is kill switch, policy, accessibility, provider,
  quality, then latency. Only the selected signal is validated, and signals are
  not combined by restrictiveness. A voice kill switch can win over a blocking
  policy signal. Caller integration must enforce any independent safety floor.
- Every selected trigger forces a downgrade. An equal/higher target takes the
  next lower tier; a request for voice while already in text yields unavailable.
  This is not the upgrade path. The trigger resolver does not re-probe the
  target, append an event or execute a renegotiation. It returns an
  event-trigger label and disclosure text. Stream kill-switch scopes are a
  separate contract, not authenticated scope enforcement inside fallback
  routing.
- Recovery defaults to 30 seconds stable and 15 seconds retry backoff. Without
  an explicit re-engagement object, it waits, then offers an available upgrade
  for confirmation. An explicit object bypasses timing even when unconfirmed;
  confirmation changes offer to attempt. Capability still gates the result.
  Neither offer nor attempt proves an executed or successful upgrade.
- Continuity copies persona, memory, grounding and history identifiers plus
  transcript state and warnings. It does not validate matching transcript
  identity or execute a handoff; buffered frame objects remain shared. The
  cursor summarizes identifiers/counts, not a signed transcript digest.

## Lilith, shell and persona depth still required

The full pinned `canonical-adapter.ts` and `crisis-safety-analyzer.ts` were also
reviewed. The policy pages distinguish the default crisis overlay from
incomplete runtime fan-out. The canonical object spreads the injected API and
retains its raw `analyzeSafety` method without an overlay; the added
`assessSafety`, `checkTopicScope`, `evaluateInteraction` and prompt-overlay path
use the merged analysis. An explicit replacement analyzer can replace the
default catalog. Backend or response-validator rejection propagates instead of
returning a synthetic block result. Consumers must choose the correct method,
validate inputs and handle failure safely.

Five additional tests in `pinned-lilith-overlay.test.mjs` execute the actual
merge and canonical adapter. Pairwise known category/risk values and boolean
escalation flags verify monotone merging. Isolated assessment calls demonstrate
default-factory binding, the untouched raw method, explicit analyzer replacement
and rejected dependencies. The crisis-catalog factory is controlled and the
assessment builder captures its input; unused detector, pack-resolution and
disposition dependencies throw. These tests do **not** exercise the real crisis
detector, complete policy assessment, all adapter methods, authenticated
consumer or runtime suppression. Full detector catalogs, tenant constraints,
stillness/re-entry/check-ins, policy versioning and actual authenticated callers
still need dedicated review and teaching.

The shell page describes invocation registries, guards, context sanitization,
four mode descriptors, persona handoffs, indicators and bridge libraries. These
are distinct from live model/domain integration. In particular, a returned
`continuityPreserved: true` flag is not evidence of durable transcript recovery.
The shell's claim that it cannot bypass substrate policy still needs actual
consumer-path evidence; a type or indication of session-only scope is not itself
proof that no profile write occurred.

The persona registry's `PersonaRecord`, nine families and seven role
definitions, separate shared `Persona` schema, opaque policy reference,
`ConsentLedger`, eight-state approval lifecycle and legacy aliases need focused
teaching. Keep local contract checks distinct from authentic consent, applied
watermarks, delivered media and retirement/recovery. The mentor page's dated
2026-07-06 state describes default-off authored performance integrations, with
human lineage/release review still open, a drafted cast, unavailable live
embodiment and pending mobile thermal/battery integration. Its subsequent
broader delivery prose is not evidence those open gates passed.

## Remaining work

The updated section 10 contract now requires content-led authoring, a complete
pilot and reader evidence before broader template migration. Per-guide art
direction is recorded in `authoring/composition-pilot.json`; this guide's
opening and runtime decision are pilot candidates, not accepted new treatments.
The shared member journey is the initial recurrence candidate. Its script,
replacement recording and current reviewed visuals supersede the older five-step
flow. Normal-speed listening and willing-reader evidence remain separate from
automated capture, decoding and source-module tests.

The
[current verification](../verification/composition-pilot-2026-09-06/README.md)
supersedes the initial draft's invalidated HTML hash. All fifteen current slides
pass draft standalone checks and the complete center's embedded/PDF checks; six
tracks are current and nine remain pending. The model visual ledger covers every
page at full size and records open composition findings: the generic opening,
linear runtime decision, unordered ordinals, three mobile tables losing row
identity and the missing visible latency-dash legend. Member-day also has
current page-fit PDF and compact/mobile embedded end-state review. Complete the
remaining pilot, narration and final guide review; mechanical checks do not
replace required normal-speed listening or reader evidence.

Continue full envelope/capability, adapter, reconnect/replay, transcript merge,
crisis-frame/audit, avatar/viseme/expression, frame-channel, Living Scenes and
provider implementations. Reconcile the distinct shell and Psyche mode gates
with real callers, then cover authenticated enforcement, data lifetime, resource
scheduling, actual media cancellation, live restoration and their
service/evaluation/release evidence. None of these five reviewed modules or the
current documentation inventory covers the entire Psyche/Lilith domain or the
whole-monorepo objective.
