# Living Scenes — Concept and Customer Promise

Living Scenes is the V1 capability that lets a customer experience a continuous,
visually responsive AI-generated video session — a contemplative arc whose
underlying segments, transitions, narration, and grounding pins are governed and
replayable, and which the user can shape live via voice, tap, or text. It serves
the contemplative product (curated cards), the AAA-Creator and operator tier
(authoring consoles in Yemaya Studio), and — for kept Living Offerings — the
public web via a per-artifact viewer. In the V1 architecture it sits _on top of_
five substrates it does not own: the Yemaya generation substrate, the Psyche
real-time runtime ([Psyche Real-Time Runtime](./psyche-realtime-runtime.md)),
the Isis governed control plane
([Isis Generation Control](./isis-generation-control.md)), the Lilith policy
substrate ([Lilith Persona Policy](./lilith-persona-policy.md)), and Sophia
grounding ([Sophia Grounding](./sophia-grounding.md)).

## The unit of delight, and the unit of safety

The **unit of delight** is "I asked for an evening walk by the sea, and it
became one — without seams; and when I whispered 'let the moon rise', it did." A
Living Scene is meant to feel like a single, unbroken stream that _listens_: the
seams between the latent video segments are smoothed by a continuity-preserving
blend, and a constrained set of live directions can reshape what comes next
while the stream is still playing.

The **unit of safety** is the inverse promise: every segment, transition, cue,
and persisted artifact is Lilith-checked, Isis-governed, Sophia-grounded where
relevant, and provenance-tracked end-to-end. Nothing reaches a viewer that has
not passed the policy gate for its template, and nothing is kept that cannot be
re-derived from its score under the same envelope. The companion pages
[Scene Safety, Determinism, Provenance, and Cue Privacy](./scene-governance.md)
and
[Keep, Share, Shareability, Takedown, and Lineage](./scene-sharing-distribution.md)
carry the full safety and lineage stories.

## What is real today, and what is the aspirational pixel layer

This is the most important framing for Living Scenes, and the docs deliberately
keep it honest. The Living Scenes code that ships in V1 is **a deterministic,
pure decision layer — not a running video renderer.** The strength of the
implementation is the _logic that decides what should happen at the boundary
between two segments, when to pre-warm the next segment, which transition is
allowed under which template, and whether a composition may be promoted_ — all
expressed as pure functions over typed contracts.

Two real packages anchor this, with exactly the names the docs cite:

- **`@yemaya/living-scenes-runtime`** (v0.1.0,
  `libs/yemaya/living-scenes-runtime/package.json`) — the Score schema, the
  Conductor state machine, the cue parser, the tone-gating allowlists, and the
  Compose-Assist tiering/gold-set machinery.
- **`@yemaya/blend-kernel`** (v0.1.0, `libs/yemaya/blend-kernel/package.json`) —
  the typed transition contracts, the 12-technique cinematographic catalog, and
  the segment-pair compatibility scorer.

What these modules **do not** do — and say so in their own source — is generate
pixels. The Conductor
(`libs/yemaya/living-scenes-runtime/src/conductor/conductor.ts`) states plainly
that it is "Pure logic… Actual GPU dispatch lives outside this module." The
Blend Kernel (`libs/yemaya/blend-kernel/src/transitions.ts`) owns the transition
contracts and parameter validation but notes "Implementations of the actual DSP
/ shader code live downstream."

Everything pixel-/frame-level is therefore **aspirational / downstream**: actual
latent video generation, optical-flow warps, FVD (Fréchet Video Distance)
computation, GPU-determinism of frames. The pure modules treat those as _score
inputs they consume_, never quantities they compute. The catalog's
`evalThresholds` (max FVD, max flicker, max color jump) are the **acceptance
bars** a downstream renderer would have to clear; the pure code does not measure
a real video against them, it carries and validates the numbers. Honest "the
decision layer is real, the renderer is downstream" beats a fake "shipped
renderer" — and that is exactly how V1 frames it.

| Layer                                                              | Status in V1              | Where it lives                                                              |
| ------------------------------------------------------------------ | ------------------------- | --------------------------------------------------------------------------- |
| Score schema + cross-field invariants                              | Real, tested              | `libs/contracts/src/living-scene/score.ts`, runtime `score/score-schema.ts` |
| Conductor scheduling state machine                                 | Real, tested              | `conductor.ts` (pure logic; "GPU dispatch lives outside")                   |
| Blend Kernel transition contracts + range validation               | Real, tested              | `transitions.ts` ("DSP/shader code lives downstream")                       |
| 12-technique catalog + per-template allowlists                     | Real, tested              | `cinematographic-catalog.ts`, `tone-gating.ts`                              |
| Segment-pair compatibility scorer                                  | Real, tested              | `compatibility/scorer.ts`                                                   |
| Compose-Assist tier caps + gold-set eval                           | Real, tested              | `compose-assist/compose-assist.ts`                                          |
| Template fixture eval-gates                                        | Real, tested              | `template-catalog.ts`                                                       |
| Latent video generation, optical-flow warp, FVD, frame determinism | Aspirational / downstream | modeled as inputs the pure functions consume                                |

## How a Living Scene plays — the data-flow promise

A Living Scene is a single perceived continuous video stream produced by
streaming a **Scene Score** through a **Conductor runtime**; the Conductor
stitches latent video segments with a continuity-preserving **Blend Kernel** and
accepts in-stream **Live Direction** cues within policy. The end-to-end flow at
V1 is:

1. The customer picks a template card (e.g. a Tara Contemplative Arc) or, on the
   compose surface, assembles a draft. The score is the durable object — see
   [Scene Score Schema](./scene-score-schema.md) for the field-level contract.
2. The Conductor walks the score's ordered `segments`, **pre-warming** the next
   `minLookaheadSegments` while the current one streams, carrying a `CarryState`
   handoff across each boundary so the incoming segment continues from where the
   outgoing one left off (clip anchor, last-frame conditioning hash, motion
   descriptor, color LUT, audio tail).
3. At each boundary the Blend Kernel applies one of nine typed transition kinds,
   chosen from the **cinematographic technique catalog** under the template's
   allowlist; see
   [Composition Surface and Cinematographic Technique Catalog](./composition-cinematography.md).
4. The customer may issue Live Direction cues (voice/tap/text) mapped to a
   constrained verb vocabulary; the Conductor and policy substrate decide
   whether and how to apply them, and the result is recorded in the score's Cue
   Plan. The runtime telemetry rides the Psyche envelope as scene events.
5. If the customer keeps the session, it becomes a **Living Offering** — a
   personal artifact that can be replayed deterministically from its score under
   the same envelope.

The runtime mechanics (Conductor state machine, Blend Kernel, Live Direction)
are detailed in
[Live Direction, Conductor Runtime, and Blend Kernel](./direction-conductor-blend.md).

## The five customer-tier templates

Five customer-tier templates ship at V1 launch, and **no template is descoped
from V1.** The docs have historically named them by friendly labels; the
canonical machine IDs live in
`libs/isis/workflow-classes/src/living-scene/template-catalog.ts`
(`LIVING_SCENE_TEMPLATES`) and are what every gate, allowlist, and score
actually references. The two must be read together — the friendly name is for
people, the machine ID is the source of truth.

| Friendly name               | Canonical template ID        | Persona / domain             | Notable policy posture                                                                    |
| --------------------------- | ---------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------- |
| Tara Contemplative Arcs     | `tara-contemplative-arc`     | Tara, contemplative practice | strictest Lilith tone band; reduced-motion variant required; no Sophia grounding required |
| Nyx Sky Briefings           | `nyx-sky-briefing`           | Nyx, sky events              | Sophia grounding correctness gated (≥0.92)                                                |
| Veritas Grounded Explainers | `veritas-grounded-explainer` | Veritas, grounded claims     | `morph` forbidden; Sophia grounding required; highest golden/adversarial bars             |
| Metis Lesson Visualizers    | `metis-lesson-visualizer`    | Metis, tutoring              | Sophia grounding required; Themis assessment interlock                                    |
| Arete Living Offerings      | `arete-living-offering`      | Arete, reflection            | intent capture required before scoring; operator-curated technique tier                   |

Each template is an authored workflow class bound to a persona, an allowed cue
verb set, a tone band, and a fixture set used for the release-gate eval (see
[Domain Templates and the Scene Score Editor](./domain-templates-and-editor.md)).
Tara additionally ships five concrete sub-variants (`TARA_SUBVARIANTS`:
`loving-kindness`, `body-scan`, `breath-anchor`, `nature-immersion`,
`gratitude`), each with a real `BreathCycle` — for example `loving-kindness` is
`inhale 4s / holdIn 1s / exhale 6s / holdOut 1s`
(`libs/isis/workflow-classes/src/living-scene/tara.ts`).

## Living Offerings are personal, persistent, replayable artifacts

Living Offerings are personal artifacts: a user can keep a session, return to
it, share it via private link or public surface, and re-render it
deterministically from its score under the same envelope; **offerings persist
for the lifetime of the user account by default.** Determinism is not a nicety —
it is the mechanism by which "this is _my_ scene, and it will be the same scene
tomorrow" is true. Because the kept object is the score plus its Render Envelope
(and not a fragile pixel blob), the artifact is portable across approved GPU
nodes within Isis-defined tolerance. The keep/share/takedown/lineage mechanics
are covered in
[Keep, Share, Shareability, Takedown, and Lineage](./scene-sharing-distribution.md).

## Surfaces: what the customer sees vs. what authors touch

The customer surface exposes only **score templates, not raw graphs** — a viewer
never composes generation graphs directly. The real surfaces in code are:

- **Public / contemplative viewer** —
  `apps/oshun/web/src/app/scene/[id]/page.tsx`, plus the embed and report
  variants `apps/oshun/web/src/app/scene/[id]/embed` and
  `apps/oshun/web/src/app/scene/[id]/report` (the directory also carries an
  `oembed` route).
- **Compose surface** (curated composition, within tier caps) —
  `apps/oshun/web/src/app/studio/compose` (`ComposeClient.tsx`) and the mobile
  `apps/oshun/mobile/app/compose.tsx`. See
  [Composition Surface and Cinematographic Technique Catalog](./composition-cinematography.md).
- **AAA-tier Scene Score editors** —
  `apps/yemaya/studio-web/src/score-editor/ScoreEditorPage.tsx` (and the desktop
  twin under `apps/yemaya/studio-desktop`). A second Scene/Tara editor also
  lives on the Oshun web app at
  `apps/oshun/web/src/app/lilith-studio/scenes/TaraSceneEditor.tsx` (with
  `/lilith-studio/scene/new`) — a "Lilith Studio" surface that sits on the
  contemplative product. (Earlier companion docs claimed the AAA score editor
  "does not appear on the contemplative product under any entitlement"; the
  presence of this Lilith Studio surface complicates that strict claim, so V1
  treats the boundary as "AAA full editor in Yemaya Studio; a constrained Lilith
  Studio scene surface exists on Oshun web.")

The full surface map is in [Product Surfaces](./product-surfaces.md) and the
tier boundaries in
[Generation Audience Tiers and Surface Boundaries](./generation-tiers-and-surfaces.md).

## The BFF and the live telemetry surface

The customer-facing HTTP layer is the BFF route
`apps/oshun/bff/src/routes/living-scenes.ts` (≈1,871 lines), which carries the
real keep / share / idempotency logic and is exercised end-to-end by
`scene-viewer-deepening.spec.ts`, `living-scene-card.spec.ts`, and
`public-scene-abuse-report.spec.ts` (per
`WALKTHROUGH/results/v1-triage-2026-06-23.md`).

During playback the **Live Direction Channel** telemetry rides the Psyche
envelope as eight scene events
(`libs/oshun/embodiment-psyche/src/events/scene-events.ts`,
`SCENE_EVENT_KINDS`): `scene.segment-start`, `scene.segment-end`,
`scene.transition-start`, `scene.transition-end`,
`scene.live-direction-applied`, `scene.policy-intervention`,
`scene.crisis-frame`, and `scene.fallback-engaged`. A `verifyEventStream` check
enforces a monotonic, gap-free sequence under a single trace id, so a viewer and
an operator inspecting the same session see one coherent feed. This event
surface is what lets the safety story be observed, not just asserted.

## Why it works this way

The split — rich pure logic, downstream pixels — is deliberate and it pays off
in three ways. First, **determinism is testable without a GPU**: the score, the
conductor decisions, and the gate verdicts are pure functions, so the release
gate ("failing reproducibility blocks promotion") can be evaluated against typed
inputs rather than flaky frame buffers. Second, **safety is enforced where it is
decidable**: the compatibility scorer's hard-incompatible policy gate, the
crisis-collapse allowlist, and the per-template technique allowlists all run
over metadata the system fully controls, so they cannot be defeated by what a
model happens to render. Third, **the kept artifact is small and portable**: a
Living Offering is a score plus an envelope, re-renderable anywhere approved,
which is what makes lifetime persistence and cross-node replay tractable.

## Related

- [Scene Score Schema](./scene-score-schema.md) — the field-level Score /
  Segment / Cue / Render Envelope contract.
- [Live Direction, Conductor Runtime, and Blend Kernel](./direction-conductor-blend.md)
  — the runtime mechanics of pre-warm, carry-state, and transitions.
- [Composition Surface and Cinematographic Technique Catalog](./composition-cinematography.md)
  — the 12 techniques and per-template allowlists.
- [Domain Templates and the Scene Score Editor](./domain-templates-and-editor.md)
  — the five templates, Tara sub-variants, and editors.
- [Scene Safety, Determinism, Provenance, and Cue Privacy](./scene-governance.md)
  — the safety, determinism, and cue-privacy story.
- [Keep, Share, Shareability, Takedown, and Lineage](./scene-sharing-distribution.md)
  — kept Living Offerings, sharing, and takedown.
- [Scene Latency, Accessibility, Eval Sets, and Tests](./scene-quality-and-eval.md)
  — the fixture eval-gates and quality bars.
- [Psyche Real-Time Runtime](./psyche-realtime-runtime.md) — the envelope the
  scene events ride on.
- [Mentor Presence — Meditating with a Master](./mentor-presence.md) — the
  embodied-mentor layer that composes with the Tara Contemplative Arc as a
  presence layer of the score (§36; implemented, release-gated).
- The features hub: [../features.md](../features.md).