Eve library

Psyche/Lilith learning map and pinned-code boundaries

Guide

Revision 1

On this page

Source revision: 1ceae52c7896a59ac74a4429d410f3218f0b91c6. This is a partial review for the full continuation plan, 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 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 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.