Skip to content

Implementation Log: ANU-11 - Build the Anuva Bento Contract and Deterministic Player

Changes and decisions

Phase Change or decision Evidence
Start Started ANU-11 through the guarded CLI after explicit approval. Branch codex/anu-11-build-the-anuva-bento-contract-and-deterministic; receipt 20260725T043141Z-work-start-058d
Plan Product Main approved proceeding after ANU-10 with Unity/Vuplex and performance work deferred. Girish approved implementation after clarifying that Emphasis follows the same document rules as Main and Companion. Approved Implementation Plan
Baseline Preserved Bento 1.0.8 and the ANU-10 adapter before production changes. Base/origin 94d7f05c0717d6e0d29b99c1d202978fa5824c29; upstream 55e4d0fcda49d588ee5620f79b8ac7d0d733cdfc
Contract Added private @anuva/bento-contract 1.0.0 with ES2022-only compilation, declarations, closed structural schema, stable errors, compatibility, and pure transforms. packages/anuva-bento-contract/; 103 focused checks
Surface rule Main, Companion, and Emphasis share identical validation and playback semantics. Transparency is optional for every kind. Opaque representative fixtures plus a valid transparency probe for each surface kind
Identities Added stable presentation, revision, surface, slide, element, fragment, event, template, and asset identities with duplicate and dangling-reference checks. Runtime validator and generated invariant cases
Compatibility Added exact contract, protocol, player, and Bento versions with required capabilities and pure consumer evaluation. Repository-local CMS, Python, and Unity declarations
Player Promoted the read-only player to protocol/player 1.0.0, stable lifecycle/errors, all approved commands, stable fragments, and immutable absolute-time reconstruction. Player and message bridge source; Web self-test
Assets Added declared media type and SHA-256 integrity, exact-locator redirect denial, external non-font assets, embedded fonts, and readiness gating. Adapter tests and browser readiness
Browser Fixed a host-only iframe boot race found by real-browser testing by waiting for the player's explicit ready marker. In-app browser self-test passed after emitted build reload
Review Closed review gaps in nested schema validation, fragment-to-slide references, command capabilities and event correlation, concurrent-load cancellation, chart snapshots, stable asset errors, and verified-byte rendering. 2026-07-25 completion review; focused Node and emitted-browser regression evidence
Packaging Added a player-only Vite entry and deterministic artifact packager that rejects editor/update/collaboration markers and retains schema, compatibility, license, and notices. Manifest covers 10 distributed inputs; 11 files including the manifest; repeatable hash
Docs Added normative contract, compatibility, API, error, security, packaging, and consumer handoff pages. docs/contracts/

Source-change map

Server-safe package

  • packages/anuva-bento-contract/src/ owns pure types, constants, protocol, runtime validation, compatibility, and transformations.
  • The package compiles with lib: ["ES2022"] and has no runtime dependency.
  • schemas/presentation.schema.json and compatibility.json are distributed alongside the ESM package.

Player and adapters

  • slides/src/anuva/contract.ts is now the typed Bento-document adapter over the built server package.
  • clock.ts derives equal surface state and stable fragments from absolute time.
  • player.ts owns lifecycle, deterministic rendering, commands, events, and optional per-surface transparency.
  • bridge.ts owns same-origin/source structured messaging and stable responses.
  • assets.ts owns bounded external fetch, media type, redirect, SHA-256, verified-byte blob materialization, chart snapshots, dehydrate, and all-document readiness behavior.
  • fixtures.ts, the Web host, and editor entry provide representative repository-local evidence.

Packaging and tests

  • vite.anuva-player.config.ts emits only the production player graph.
  • scripts/package-anuva-player.ts assembles and hashes the static artifact.
  • scripts/test-anuva-contract.ts contains server, schema, property-style, compatibility, and equal-surface checks.
  • scripts/test-anuva.ts contains Bento adapter, integrity, clock, fragment, network, and template checks.

Preserved upstream seam

slides/src/update.ts remains the sole existing Bento product-source seam. It uses the ANU-10 hard-offline compile flag and was not broadened by ANU-11.

Verification evidence

Check Result
npm ci Passed; 79 packages, 0 vulnerabilities
Baseline upstream build Passed
Windows-equivalent single-file build Passed; 1,170 KB to 580 KB
node ..\scripts\test-sync.ts Passed; 45,362 checks
Baseline ANU-10 tests Passed; 29 checks
Contract build Passed with ESM and declarations
ANU-11 contract tests Passed; 103 checks
ANU-11 adapter tests Passed; 37 checks
Anuva Web build Passed
Player-only build Passed; player JavaScript 55.39 kB, gzip 19.00 kB
Web host self-test Passed correlated events, safe hidden failure/recovery, concurrent-load cancellation, verified-byte assets, and all commands across Main, Companion, and Emphasis
Packaged player smoke Passed; boot marker, Main surface, and generator anuva-bento-player-1.0.0
Contract tarball inspection Passed; 34 files, 21.0 kB packed, license/notices present
Contract tarball SHA-256 43000c5b1aac6181f0b66610f0f8e883b8e3eea860f964e487c9575371922072 on two builds
Player manifest SHA-256 cd25840e5bf15ccb8fc2abefab054698c46b2dea15a03c9115cf89c6b490328f on two builds

Tool identity: Node v24.18.0, npm 10.9.2, TypeScript 5.8.3, and Vite 7.3.6.

The in-app browser controller logged one MutationObserver type error while instrumenting each fresh tab. The loaded host/player artifact graph contains no MutationObserver reference, the error did not originate from an emitted application module, and the host still reached its explicit pass state. The production player build also contains no such reference.

Deferred and skipped checks

  • Unity/Vuplex embedding, transport, transparency, lifecycle, and capture were not run by approved scope.
  • Performance, profiling, startup latency, memory, CPU/GPU, frame time, and concurrent-player testing were not run by approved scope.
  • Registry publication, GitHub Release creation, production deployment, and canonical documentation publication were not run.