docs(devlog): cover runtime phases 1 and 2

2026-09-05 13:00:23 -07:00
parent c010e415a2
commit 12140055f7
1 changed files with 51 additions and 0 deletions
@@ -0,0 +1,51 @@
+_model: devlog-entry
+---
+schema_version: 1
+---
+title: Building the standalone runtime and its common grammar
+---
+date: 2026-09-05
+---
+author: Labyricorn
+---
+summary: Phases 1 and 2 turn XZBT's validated contracts into a deterministic standalone browser runtime with exhibit import and caching, controlled lifecycle management, seeded randomness, typed values, bindings, actions, transitions, and temporary overrides.
+---
+tags: Runtime, Common Grammar, Deterministic Testing, Phase 1, Phase 2
+---
+source_commit: c010e415a2871213426600e0b1fbe782cd65a0b1
+---
+body:
+
+XZBT now has its first production runtime. Phases 1 and 2 move the project beyond feasibility probes and contract models into a self-contained application that can load declarative exhibits and execute their shared value grammar.
+
+The [Phase 1 and 2 implementation commit](https://git.labyricorn.com/Labyricorn/XZBT/commit/c010e415a2871213426600e0b1fbe782cd65a0b1) builds separate source modules into one `XZBT.html` artifact. The build is deterministic, contains its runtime code and styles inline, and has no external script or stylesheet dependency. Two small subject-neutral `.xzbt` exhibits exercise the loader and common grammar without adding exhibit-specific JavaScript to the runtime.
+
+## Establishing the runtime skeleton
+
+Phase 1 introduces the application shell, exhibit library, validation boundary, diagnostics, lifecycle control, random streams, and local cache.
+
+Imported exhibits are decoded as JSON, checked for XZBT version and metadata requirements, fingerprinted with SHA-256, and stored in IndexedDB when browser storage is available. Cached definitions and the last active exhibit can be restored on a later launch. If storage fails, the application remains usable for the session and reports the limitation instead of treating persistence as successful.
+
+Activation is deliberately controlled. A candidate performance is prepared before the current exhibit is torn down. Deactivation clears owned resources, and a failed replacement attempts to restart the previous valid exhibit. The current Phase 1 performance surface is intentionally small, but it establishes the ownership boundary later audio, visual, cadence, and scenario systems will use.
+
+The production random-number implementation preserves the Phase 0 contract: FNV-1a stream derivation, SplitMix32 state expansion, `xoshiro128**` output, and isolated domains. The known GC4 seed and output vectors pass against the production module rather than only the earlier contract oracle.
+
+## Adding the common grammar
+
+Phase 2 gives exhibits a typed shared data model. Parameters remain user-owned and are persisted separately per exhibit. State remains simulation-owned and starts fresh with each performance. Runtime signals expose logical time, pointer position, viewport size, future audio-analysis inputs, and scenario activity as read-only values.
+
+The ValueSpec evaluator handles literals, references, bounded random values, weighted choices, and the documented safe numeric operators. ConditionSpec adds strict comparisons and short-circuiting logical composition. No implicit coercion or arbitrary executable expression is introduced.
+
+Bindings resolve dependencies in the same logical tick. Numeric bindings support scale, offset, clamps, and the specified deterministic one-pole smoothing behavior. A disabled binding exposes the target's base value, and re-enabling it initializes cleanly without replaying disabled time.
+
+The common action executor implements ordered state mutation and temporary overrides. Later actions observe earlier state changes in the same action array, while `set` is prevented from mutating user parameters. Numeric state changes can transition through the documented easing functions.
+
+Overrides receive deterministic runtime IDs and compete by priority followed by activation sequence. They may be scenario-owned or duration-bound, can attack and release over logical time, and never destroy the stored parameter beneath them. If a user edits a masked parameter, releasing the override returns toward that current stored value rather than an obsolete snapshot.
+
+## Verification and current boundary
+
+The production Phase 1 suite passes six tests covering fixtures, failure diagnostics, PRNG vectors, cache behavior, activation recovery, and reproducible self-contained builds. The Phase 2 suite passes nine tests covering the GC2 fixture matrix, ValueSpec, ConditionSpec, binding order and smoothing, ordered actions, transitions, override behavior, parameter restoration, and disposal. The unchanged GC2 through GC5 contract-oracle suites also pass.
+
+The built artifact recorded for this milestone has SHA-256 digest `8ea318535e97b25b51760b6c0e59e1a5af89d3f429f079de3b87230165008517`.
+
+This milestone does not claim that the later subsystem phases are complete. Audio synthesis, visual rendering, cadence and events, scenario direction, the final generated UI, library hardening, reference exhibits, benchmarks, and soak tests remain ahead. The repository also continues to mark the production artifact's user-observed direct-file import and full-browser restart check as open because the available browser automation could not perform that `file:` navigation without violating the recorded test boundary.