Labyricorn/XZBT
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(runtime): implement phases 1 and 2

Browse Source
This commit is contained in:
Labyricorn
2026-09-05 12:59:15 -07:00
parent 75b4da0df4
commit c010e415a2
27 changed files with 4172 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/IMPLEMENTATION_STATUS.md
+11 -5
View File
@@ -1,18 +1,18 @@
# XZBT implementation status
**Updated:** September 5, 2026
**State:** Phase 0 complete; ready to begin Phase 1 runtime skeleton
**State:** Phase 2 common grammar complete; Phase 1 direct-file import/restart observation remains pending
**Planning baseline:** `05fe2b4e021ba86e4a290d05b63c7cae0e386128`
**Exact demarcation:** GC1 direct-file feasibility (10/10 checks), GC2 shared format contracts, GC3 resolution semantics, GC4 clock/PRNG semantics, and GC5 ownership/failure semantics are complete at the Phase 0 contract-oracle level. The implementation plan maps GC6 measurements and GC7 completion/library/build checks to later milestones. No production runtime work has begun; real subsystem, Web Audio synchronization, performance, and soak evidence remain assigned to Phases 1–9.
**Exact demarcation:** GC1 direct-file feasibility (10/10 checks), GC2 shared format contracts, GC3 resolution semantics, GC4 clock/PRNG semantics, and GC5 ownership/failure semantics are complete at the Phase 0 contract-oracle level. The Phase 1 production runtime skeleton and Phase 2 common grammar are implemented and pass automated checks, but Phase 1's direct-file two-fixture restart observation remains open. Real audio, visual, cadence/event, scenario, final generated-UI, performance, and soak work remains assigned to later phases.
The user requested sequential implementation with a stop on problems. The [manual version 3 evidence](evidence/phase0/2026-09-04-user-run-v3.md) verifies embedded data-URL worklet loading in direct-file Chrome. The subsequent [user-performed restart test](evidence/phase0/2026-09-04-user-restart.md) restored Blue Study activity 0.37 and master volume 0.19 immediately on reopening. Native tone output and AudioContext suspend/resume are also observed. Ordinary file import, selection of both exhibits, regular Chrome mode, and [directory cancellation/denial fallback](evidence/phase0/2026-09-05-user-directory-fallback.md) have been confirmed.
| Phase | Status | Evidence or next prerequisite |
| --- | --- | --- |
| 0 — Contracts and feasibility | Complete | GC1 passed; GC2–GC5 shared contracts and traces passed; GC6/GC7 later gates scheduled and mapped |
| 1 — Runtime skeleton | Ready | Follow the [implementation plan](XZBT_0-1_Implementation_Plan.md) and preserve Phase 0 contract oracles |
| 2 — Common grammar | Not started | Complete Phase 1 and shared contracts |
| 1 — Runtime skeleton | Implemented; acceptance pending | [Automated evidence](evidence/phase1/2026-09-05-runtime-skeleton.md) passes production-module, lifecycle, PRNG-vector, cache/restore, fixture-validation, and deterministic-build tests. Direct-file two-fixture import/restart remains a user-observed gate. |
| 2 — Common grammar | Complete | [Automated evidence](evidence/phase2/2026-09-05-common-grammar.md) covers production GC2 conformance, typed values, signals, actions, same-tick bindings, transitions, override precedence/release, and parameter restoration. |
| 3 — Audio engine | Not started | Earlier phases and audio contracts |
| 4 — Visual engine | Not started | Earlier phases and visual contracts |
| 5 — Events and cadence | Not started | Earlier phases and event/cadence contracts |
@@ -43,4 +43,10 @@ The browser rejection explicitly forbids agent workarounds through alternate bro
A dependency-free loopback development server is available at `tools/dev-server.mjs`. It serves the workspace at `http://localhost:5173/` for later automated development testing only and listens on both IPv4 and IPv6 loopback. It may support source-level UI or regression work after Phase 0, but direct-file operation remains the primary distribution architecture.
Phase 0 is complete. Begin Phase 1 with the runtime skeleton and reproducible modular-source build described in the implementation plan. Reuse the GC4 PRNG known vectors in the production `SeededRNG`; do not reinterpret the frozen GC3–GC5 contracts silently. The mandatory combined-load measurements, production subsystem conformance, two-hour development soak, and eight-hour release soak remain outstanding at their mapped later gates.
Phase 0 remains complete and the Phase 1 implementation now reuses the GC4 PRNG known vectors in the production `SeededRNG`. The mandatory direct-file Phase 1 observation, combined-load measurements, production subsystem conformance, two-hour development soak, and eight-hour release soak remain outstanding at their mapped gates.
## Phase 1 implementation
The modular runtime sources now live in `src/runtime` and build deterministically with `node tools/build-xzbt.mjs` into the self-contained root `XZBT.html`. The artifact has no external runtime dependencies or requests. Two minimal, subject-neutral fixtures live in `exhibits`; one uses fixed seed `42` and one requests cryptographic entropy. Phase 2 extends both with small common-grammar examples.
Automated Phase 1 checks cover JSON/version/metadata failure, the frozen GC4 state/output vectors, byte-identical import behavior, in-memory restore, prepare-before-teardown activation recovery, and byte-identical standalone builds. The existing GC2–GC5 suites still pass when run in-process. Phase 1 is not marked accepted until the built artifact imports both fixtures directly from disk, restores them after a full browser restart, and records the Phase 1 GC6 environment details required by the implementation plan.
docs/evidence/phase1/2026-09-05-runtime-skeleton.md
+35
View File
@@ -0,0 +1,35 @@
# Phase 1 runtime skeleton — automated evidence
**Date:** September 5, 2026
**Artifact:** `XZBT.html`
**SHA-256:** `8a444a17e06e3d2c4825fcb293004fde4da22c776154fba3d624cc50845c26c3`
**Result:** Implementation and automated verification passed; direct-file restart observation remains pending.
## Delivered
- deterministic modular-source build into one inline-script, inline-style HTML artifact;
- multi-file and drag/drop `.xzbt` loading;
- BOM-aware JSON parsing plus XZBT version, metadata, identifier, root-field, and seed validation;
- exhibit library and inert Phase 1 performance surface;
- prepare-before-teardown activation, complete disposal, and previous-exhibit recovery attempt;
- production `SeededRNG` using the frozen FNV-1a-32, SplitMix32, and `xoshiro128**` contract;
- IndexedDB definition cache and last-active-exhibit preference, with a visible session-only fallback;
- bounded structured diagnostics with severity, code, exhibit, section, object, property, and explanation fields;
- two minimal valid exhibits: fixed-seed and cryptographically randomized.
## Automated verification
`npm run test:phase1` passed 6 of 6 tests. Coverage includes both fixtures, malformed/version/metadata rejection, frozen GC4 PRNG vectors, identical-import no-op and restore, activation failure recovery, byte-identical clean builds, absence of external script/style dependencies, and generated-script compilation.
The existing in-process contract suites also passed unchanged:
- GC2: 12 of 12
- GC3: 8 of 8
- GC4: 7 of 7
- GC5: 8 of 8
`git diff --check` reported no whitespace errors.
## Open acceptance observation
The repository records that prior browser tooling was not permitted to navigate directly to a `file:` URL, and forbids substituting another browser surface or raw command as a workaround. Consequently, this record does not claim the final Phase 1 direct-file acceptance observation. A supported desktop Chromium user run still needs to import both files from `exhibits`, switch between them, close the full browser, reopen the same `XZBT.html`, confirm that both cached exhibits return and the last exhibit activates, and record the Phase 1 GC6 environment fields.
docs/evidence/phase2/2026-09-05-common-grammar.md
+52
View File
@@ -0,0 +1,52 @@
# Phase 2 common grammar — automated evidence
**Date:** September 5, 2026
**Artifact:** `XZBT.html`
**SHA-256:** `8ea318535e97b25b51760b6c0e59e1a5af89d3f429f079de3b87230165008517`
**Result:** Phase 2 implementation and automated acceptance passed.
## Delivered
- typed parameter and simulation-state stores with strict coercion rejection and declared bounds;
- separately persisted parameter snapshots, with state recreated for each performance;
- read-only time, audio-analysis placeholder, pointer, viewport, and scenario-active signals;
- literal, reference, bounded random, weighted-choice, and safe-operation ValueSpec evaluation;
- comparison and short-circuit logical ConditionSpec evaluation;
- deterministic fixed-step common-grammar performance driver with the GC4 stall bound;
- same-tick dependency resolution for parameter/state bindings;
- numeric transforms, clamps, exact one-pole smoothing, conditional disable, and clean re-enable;
- ordered common action execution with `when`, `chance`, `critical`, persistent state `set`, and temporary `override`;
- numeric set transitions with the four standard easing modes;
- override runtime IDs, priority/activation-sequence precedence, scenario/duration lifetimes, attack/release transitions, owner release, and live lower-value restoration;
- generic inspection controls and resolved-value placeholders in the subject-neutral application shell;
- two updated minimal exhibits exercising conditional and unconditional common-grammar bindings.
Subsystem-specific `sound`, `event`, `spawn`, `remove`, and `control` execution remains unavailable until the owning audio, visual, event/cadence, and scenario phases define and implement their capability contracts. The common executor rejects those actions explicitly instead of approximating their behavior.
## Automated verification
`npm run test:phase2` passed 9 of 9 production tests:
1. production validator agreement with the GC2 fixture matrix;
2. ValueSpec references, random values, weighted choice, safe operations, and arity failure;
3. ConditionSpec composition, short-circuiting, and strict operand typing;
4. same-tick binding dependency order and exact smoothing;
5. conditional binding disable and re-enable behavior;
6. document-order state actions and parameter mutation rejection;
7. deterministic state transitions and duration parsing;
8. override precedence, stored-edit preservation, and live-base release;
9. duration expiry, compatible stored parameters, and performance disposal.
Regression verification also passed:
- Phase 1 production/build tests: 6 of 6
- GC2 contract oracle: 12 of 12
- GC3 contract oracle: 8 of 8
- GC4 contract oracle: 7 of 7
- GC5 contract oracle: 8 of 8
The standalone build test compiled the generated script and confirmed byte-identical clean outputs with no external runtime script or stylesheet references.
## Remaining cross-phase observation
The earlier direct-file browser restriction still prevents an agent-run full-browser restart check. Phase 1’s user-observed two-fixture import/cache/reopen gate therefore remains open; it does not change the passing Phase 2 semantic results above.