Skip to content

Implementation Plan: ANU-13 - Implement PresentationConfig v2 and multi-surface compilation

Status: Approved by the user on 2026-07-27. Approved plan SHA-256: 58A93B8F4FEE0B41A8C30D644F9D5216D4776D596CB3860F45C120C1A450AACD.

Scope

Replace the active Reveal-oriented Presentation Video compilation contract with PresentationConfig v2 backed by the production Anuva Bento aggregate. Persist immutable aggregate revisions and optimistic-conflict primitives, compile complementary Main, Companion, and Emphasis documents from narrative scenes, resolve one authoritative absolute-time timeline, validate contract and consumer compatibility, resolve immutable assets, assemble a deterministic render package, and recreate development fixtures exclusively in v2.

This is a clean development-phase cutover. It does not migrate existing Reveal presentation data or keep a permanent v1/v2 dual-write path.

Product Main inputs and dependencies

  • Product Main change: 2026-07-24-anuva-bento-integration
  • Product Main source: docs/changes/2026-07-24-anuva-bento-integration/index.md
  • Linear parent: ANU-8
  • Linear implementation child: ANU-13
  • Repository label: anuvax-cms
  • Required dependency: ANU-11, completed
  • Bento source commit: merged ANU-11 commit 42dbb0a
  • Contract package: @anuva/bento-contract 1.0.0
  • Contract, protocol, and player versions: 1.0.0
  • Bento base version: 1.0.8

The normalized Linear scope, acceptance, documentation, and verification requirements are authoritative. ANU-11 owns the executable contract, validator, compatibility policy, and player artifacts. CMS owns persistence, generation, compilation, timing, asset resolution, and render-package assembly. Python and Unity consumer implementation remains outside this repository.

Contract and artifact boundary

  1. Rebuild the contract package and player bundle from the reviewed ANU-11 commit, verify their deterministic manifests and SHA-256 identities, and vendor only the immutable consumer artifacts needed by CMS builds and render packages. Retain the Bento license and third-party notices and record source commit, versions, and checksums in a repository-owned provenance manifest.
  2. Install the server-safe contract package from the vendored artifact so CI, clean checkouts, and local development do not depend on an unversioned sibling checkout, public registry, or mutable branch.
  3. Reject unsupported contract, protocol, player, Bento, or capability combinations before compilation persistence or render-package assembly. Do not implement best-effort parsing, runtime downloads, or version fallback.
  4. Keep credentials, signed URLs, query-bearing locators, and public Bento services outside PresentationConfig and its immutable package manifest.

Expected tracked surfaces include package.json, pnpm-lock.yaml, a narrow vendor/anuva-bento/1.0.0/ artifact/provenance boundary, and focused license/provenance tests. If the reviewed artifact cannot be reproduced from the merged dependency, stop and return the distribution gap to Product Main instead of copying an unverified local build.

Data model and revision approach

  1. Treat presentation_compilations as immutable PresentationConfig aggregate revisions. Add explicit aggregate identity, revision, parent revision, content checksum, contract/player compatibility, asset-manifest, and validation-result fields while preserving workspace and presentation relationships.
  2. Keep presentations.latestCompilation as the current aggregate pointer. Provide a repository service that creates the next revision only when the caller's expected revision/checksum matches the current pointer. On conflict, preserve the persisted revision and return stable conflict details without overwriting either side.
  3. Replace Reveal-specific fields on presentation_scenes with a typed scene-to-surface plan that supports zero or more items on each surface, stable item and element identities, preserve, replace, and clear behavior, fragment/state cues, and bounded transient emphasis.
  4. Keep narrative, voiceover, visual assignment, camera direction, and timing inputs workspace-scoped. Validate every presentation, scene, compilation, media, and audio relationship against the active workspace before writing.
  5. Regenerate Payload types after the schema cutover. No legacy data migration is planned; development data is recreated from v2 seed and fixture inputs.

Expected tracked surfaces include src/collections/anuvax/index.ts, src/payload-types.ts, new focused persistence/revision helpers under src/lib/presentation-config/, presentation actions and Mastra persistence tools, plus fake-Payload and schema integration tests.

Multi-surface planning and compilation

  1. Replace Reveal slide schemas, prompts, agents, workflow artifacts, compiler tools, validation tools, and fallback markup builders with a typed multi-surface planning contract. Each scene can intentionally emit no item for a surface and must describe whether existing surface state is preserved, replaced, or cleared.
  2. Generate complementary roles rather than duplicate narration: Main carries the primary explanatory structure, Companion carries supporting context or evidence, and Emphasis carries sparse time-bounded callouts. The deterministic compiler, not an agent, owns IDs, contract normalization, cross-reference checks, and timeline ordering.
  3. Derive stable presentation, surface, document, slide, item, element, fragment, template, event, and asset identities from immutable source identities and semantic positions, never mutable display text. Recompiling unchanged input must reproduce the same identities and checksum.
  4. Compile the three required, structurally equal Bento surface documents and translate scene operations into absolute timeline events for slide select, show, hide, clear, and fragment visibility. Main and Companion may persist across scene boundaries; Emphasis events must have an explicit end state.
  5. Resolve scene start/end authority in this order: actual TTS word timings, persisted voiceover duration, then deterministic estimate. Apply the persisted scene pause once, enforce non-negative monotonic time, and use stable tie-breaking for simultaneous events.
  6. Validate the completed aggregate with @anuva/bento-contract and run compatibility evaluation before persistence. Surface validation failures as stable typed issues; never persist a success revision after partial or best-effort compilation.

Expected tracked surfaces include src/lib/anuva/contracts-v1.ts, src/lib/anuva/deterministic-tools.ts, src/lib/anuva/workflow-graph.ts, presentation Mastra schemas, agent contracts, slide/surface workflow and compiler/validation tools, src/mastra/workflows/presentationvideo.workflow.ts, src/mastra/tools/presentation/index.ts, and the active presentation server actions. Before editing Mastra workflow code, verify the installed package APIs against the embedded node_modules/@mastra/*/dist/docs documentation.

Assets and immutable render packages

  1. Build contract asset declarations from persisted media and audio records. Require supported media type, lowercase SHA-256, stable asset identity, and a package-relative locator for every external Bento asset. Embedded assets are limited to contract-approved fonts.
  2. Materialize player files, three surface documents, timeline, compatibility metadata, asset manifest, media, fonts, license, and notices into a deterministic package layout. Every file receives a byte count and SHA-256; the root manifest receives a deterministic checksum.
  3. Keep worker authentication and any transport grants outside the serialized PresentationConfig and immutable package. Render inputs must not contain CMS credentials, signed or expiring URLs, path traversal, public Bento update endpoints, or collaboration endpoints.
  4. Replace the existing render-worker package shape that exposes PresentationConfigPublic and mutable asset URLs. Preserve job identity, workspace scoping, priority, progress, cancellation, upload, completion, and failure behavior while returning v2 package identity and immutable file descriptors.
  5. Pin exact compatible contract, protocol, player, renderer, and Bento versions in both compilation and job snapshots so Python and Unity can reject a mismatch before playback.

Expected tracked surfaces include src/lib/render-worker/service.ts, src/lib/render-worker/contracts.ts, worker API integration fixtures, video_generation_jobs.configSnapshot creation, and render-package checksum/offline/security tests.

Cutover, fixtures, and failure recovery

  1. Update seed, import/export, diagnostics, fake-Payload, Mastra runtime, unit, integration, and e2e fixtures to create v2 documents only.
  2. Remove active direct Reveal markup generation, Reveal validation, Reveal scene persistence fields, v1 public-config parsing, and render-package assumptions after the v2 path passes targeted tests. Retain no hidden fallback that can generate Reveal markup.
  3. Verify clean recreation in an isolated disposable development database. Do not reset the user's current database or named volume without a separate, explicit destructive-action approval.
  4. On validation, compatibility, asset, checksum, persistence, or revision conflict failure, keep the last accepted compilation current, record a stable failure result, invalidate render readiness, and allow deterministic retry from unchanged inputs.
  5. Keep editor embedding, autosave UI, template selection/application, AI edit operations, and shared Web player hosting out of this issue; those remain ANU-14 scope.

Expected tracked surfaces include scripts/seed.ts, scripts/seed-presentation-fixture.ts, scripts/export-presentation-fixture.ts, scripts/presentation-generation-diagnostics.ts, presentation test fixtures, and the active create/preview/render integration and Playwright coverage.

Delivery sequence

  1. Reproduce and vendor the exact Bento consumer artifacts and add provenance, import, schema, compatibility, and tamper tests.
  2. Introduce the v2 domain schemas, stable identity helpers, scene-to-surface planning model, deterministic timeline compiler, asset manifest, and package checksum helpers with unit/property tests.
  3. Cut Payload collections and repository services to immutable v2 revisions and optimistic conflict primitives; regenerate types and add persistence and tenant-boundary tests.
  4. Replace Mastra Reveal planning/compilation with multi-surface planning and validated v2 compilation; update presentation actions and integration tests.
  5. Replace render-job snapshot/package assembly with the immutable v2 layout and add compatibility, checksum, offline-asset, credential, and path-safety coverage.
  6. Convert seeds, fixtures, diagnostics, and relevant e2e mocks to v2; prove clean disposable-database recreation and remove the active Reveal path.
  7. Update durable and state documentation, complete the implementation log and completion report, run the full verification matrix, and create the linked draft PR through anuva pr create ANU-13 --draft --confirm.

Each step must leave the repository typecheckable and testable. If a material contract, persistence, package-layout, or scope decision differs from this plan, update and re-preview the plan and obtain approval again before continuing.

Documentation impact

  • Rewrite docs/core/PresentationConfig.md for v2 aggregate identity, surfaces, revisions, timing, compatibility, validation, assets, and package layout.
  • Update docs/core/PresentationVideoWorkflow.md and docs/core/MastraAgentsAndTools.md for multi-surface planning and compilation.
  • Update docs/core/PayloadDataModel.md for aggregate revisions and conflict primitives.
  • Update docs/core/WorkersAndJobs.md for immutable package handoff, structured failures, and recovery.
  • Update docs/core/TestingAndVerification.md for schemas, property checks, consumer compatibility, package integrity, offline assets, clean recreation, and Reveal-path scanning.
  • Update docs/state/CurrentImplementationMap.md, docs/state/ServerActionsMap.md, docs/state/WorkflowMap.md, docs/state/CollectionMap.md, docs/state/ScriptsAndCommands.md, and docs/state/KnownGaps.md where paths, commands, state, or resolved gaps change.
  • Maintain this change-folder plan, implementation log, completion report, recursive indexes, and MkDocs navigation. Return preview-only URLs after each logical documentation update; Product Main owns canonical publication.

Verification and acceptance checks

Acceptance area Planned evidence
Bento dependency and compatibility Reproducible ANU-11 artifact hashes, retained notices, server-safe import, exact-version compatibility pass, unsupported-version/capability rejection
Valid complementary surfaces Representative and edge-case narratives compile three required documents with intentionally distinct Main, Companion, and Emphasis roles
Stable identities and mapping Repeat compilation checksum equality; zero/many items per surface; preserve/replace/clear; fragment/state; transient emphasis tests
Authoritative timing Actual-duration-estimate precedence, pauses, monotonic absolute events, deterministic tie order, arbitrary scene-count/property cases
Persistence and conflicts Immutable revisions, parent/current pointers, compare-and-swap success/conflict, retry, workspace isolation, last-good revision preservation
Contract validation and security JSON/runtime validation, cross-reference failures, unsafe content/locator rejection, no collaboration/update endpoint or executable payload
Assets and package Per-file and root checksums, package-relative locators, exact player/runtime pins, offline manifest inspection, tamper/missing/media-type/path-traversal failures
Active-path cutover Generation, preview compilation, and render handoff use v2; repository scan plus targeted tests prove no active direct Reveal generation or v1 fixture fallback
Development data Fresh isolated database and seed/fixture round trip produces v2 only; no destructive reset of the current database
Repository quality pnpm generate:types, pnpm lint, pnpm typecheck, pnpm test:int, relevant pnpm test:e2e, consumer fixture tests, git diff --check, strict MkDocs, recursive index validation

Property-style tests will use deterministic seeded cases and record the seed for reproduction. Skipped checks, external consumer limits, and remaining cross-repository risks will be explicit in the completion report.

Non-goals and rollback

Non-goals:

  • editor embedding, autosave, AI edit operations, template UI, or shared Web player hosting owned by ANU-14
  • Unity/Vuplex lifecycle, virtual-surface mapping, performance, or capture owned by ANU-15
  • Python staging/orchestration implementation owned by ANU-16
  • publishing Bento packages or player assets to a registry or public service
  • migrating existing Reveal development records or maintaining permanent dual writes
  • changing product-level compatibility policy or the Bento-owned executable contract

Before cutover, rollback is removal of the new v2 path while the existing path remains unchanged. After the clean cutover begins, rollback means reverting the branch and recreating disposable development data from the last accepted fixture; it does not translate v2 documents back into Reveal markup. Failed compilation or package creation leaves the last accepted immutable revision current and records a structured retryable or terminal failure.