feat(phase0): complete GC1 feasibility and GC2 shared format contracts

- Record user evidence for directory fallback to complete GC1 (10/10 checks passed)

- Expand Format Specification 0.1 to Revision 0.2 with normative shared contracts

- Author JSON Schema Draft-07 at schema/xzbt-0.1.schema.json

- Implement zero-dependency semantic validator at tools/validate-exhibit.mjs

- Create 12-case conformance fixture suite and automated test runner (12/12 passing)

- Update implementation status, verification gates, and gap closure decisions

- Add devlog entry covering stall recovery and Phase 0 current state
This commit is contained in:
2026-09-05 11:38:48 -07:00
parent ca2830174f
commit e02d49a739
25 changed files with 2473 additions and 66 deletions
+14 -14
View File
@@ -1,11 +1,11 @@
# XZBT 0.1 Verification Gates
**Status:** Phase 0 awaiting remaining manual checks; worklet loading and user-performed restart persistence passed; GC1 incomplete
**Status:** Phase 0 in progress before Phase 1. GC1 (10/10 checks) and GC2 shared contracts verified; GC3–GC5 resolution, clock, and ownership contracts in progress.
**Related resources:** [PRD](../XZBT_0-1_MVP_Product_Requirements_Document.md), [decisions](XZBT_0-1_Gap_Closure_Decisions.md), [format specification](XZBT_0-1_Format_Specification.md)
A separate Phase 0 probe has been created and its JavaScript/JSON syntax checked. The agent's direct-file navigation was blocked by browser tool policy; see the [attempt record](evidence/phase0/2026-09-04-feasibility.md). The [user's manual run](evidence/phase0/2026-09-04-user-run.md) reports successful import, saves, and context unlock, but worklet loading failed. Version 2 separates the tests and records better diagnostics; its two stubbed regression tests pass, not its browser gate. GC1, benchmark, and soak acceptance remain incomplete. Mark a check complete only with linked evidence; a partial result does not pass a compound acceptance check.
A separate Phase 0 probe has been created and its JavaScript/JSON syntax checked. The agent's direct-file navigation was blocked by browser tool policy; see the [attempt record](evidence/phase0/2026-09-04-feasibility.md). The [user's manual run](evidence/phase0/2026-09-04-user-run.md) reports successful import, saves, and context unlock, but worklet loading failed. Version 2 separates the tests and records better diagnostics; its two stubbed regression tests pass, not its browser gate. Mark a check complete only with linked evidence; a partial result does not pass a compound acceptance check.
The [second user run](evidence/phase0/2026-09-04-user-run-v2.md) confirmed cache restoration between page loads, a heard tone, and audio suspend/resume, but Blob worklet loading failed. The [version 3 user run](evidence/phase0/2026-09-04-user-run-v3.md) verified the embedded-data-URL fix. The subsequent [manual restart test](evidence/phase0/2026-09-04-user-restart.md), supplied after the explicit full-exit procedure, restored edited activity and volume with zero new saves. The directory-permission/unavailability fallback observation remains pending.
The [second user run](evidence/phase0/2026-09-04-user-run-v2.md) confirmed cache restoration between page loads, a heard tone, and audio suspend/resume, but Blob worklet loading failed. The [version 3 user run](evidence/phase0/2026-09-04-user-run-v3.md) verified the embedded-data-URL fix. The subsequent [manual restart test](evidence/phase0/2026-09-04-user-restart.md), supplied after the explicit full-exit procedure, restored edited activity and volume with zero new saves. The [directory fallback observation](evidence/phase0/2026-09-05-user-directory-fallback.md) confirmed graceful error handling and state preservation when directory access is cancelled/denied; GC1 is now fully passed. Furthermore, GC2 shared contracts, the JSON Schema, the semantic validator, and the 12-case test suite are verified; see [GC2 evidence](evidence/phase0/2026-09-05-gc2-format-contracts.md).
## Phase 0 and later gates
@@ -15,8 +15,8 @@ Subsystem-specific format details can be completed in dependency order as planne
| Gap | Decision | Evidence status | Gate placement |
| --- | --- | --- | --- |
| GC1 | Recorded | Data-URL worklet load and user-performed restart/settings restoration passed; remaining manual checks pending | Phase 0, before deployment architecture commitment |
| GC2 | Recorded; format draft partial | Contracts and fixtures incomplete | Shared contracts in Phase 0; subsystem contracts before their implementation |
| GC1 | Recorded | Passed; all 10 direct-file feasibility checks verified with linked empirical evidence | Phase 0, before deployment architecture commitment |
| GC2 | Recorded; shared contracts complete | Shared document, types, ValueSpec, ConditionSpec, schema, validator, and 12-case fixture suite verified; subsystem contracts in dependency order | Shared contracts in Phase 0; subsystem contracts before their implementation |
| GC3 | Recorded; transition details open | Traces and tests pending | Shared resolver contract before Phase 2; tests with implementation |
| GC4 | Recorded; audio mapping details open | Prototype and tests pending | Clock contract in Phase 0; synchronization tests in audio integration |
| GC5 | Recorded; hook/queue details open | Traces and tests pending | Ownership contract before actions/audio; full tests with scenarios |
@@ -34,21 +34,21 @@ Subsystem-specific format details can be completed in dependency order as planne
- [x] If needed by the audio design, load engine-owned AudioWorklet code from the single-file artifact. Verified with the data-URL module in the version 3 user run.
- [x] Test renamed and moved HTML files; record observed storage behavior and the support boundary. The user confirmed restoration from both copies; see [file-location evidence and limits](evidence/phase0/2026-09-04-user-file-locations.md).
- [x] Test unavailable/failed storage; session playback works and the UI explains lack of persistence. [Injected-failure evidence](evidence/phase0/2026-09-04-user-storage-failure.md) confirms settings changes, import, and heard native playback remain operational with zero successful writes; the user subsequently confirmed the visible session-only warning. Passed using application fault injection, not real browser permission denial.
- [ ] Test directory import/remembered handles where available and ordinary-picker fallback where unavailable or permission is denied. Directory import completed in the injected-failure run and ordinary import/activation passed separately. Actual denial/unavailability fallback remains unverified. Remembered handles are optional and not implemented in this probe; verification is required if implemented in the runtime.
- [x] Test directory import/remembered handles where available and ordinary-picker fallback where unavailable or permission is denied. Directory import completed in the injected-failure run and ordinary import/activation passed separately. Directory cancellation/denial fallback is verified with preserved session state; see [directory fallback evidence](evidence/phase0/2026-09-05-user-directory-fallback.md). Remembered handles are optional and not implemented in this probe; verification is required if implemented in the runtime.
**Evidence:** prototype artifact, reproducible steps, environment record, observed results. If ordinary-mode persistence fails, reopen decision 1 before dependent architecture commitment.
## 2. GC2: Format contract completeness
- [ ] Complete shared document, type, reference, ValueSpec, ConditionSpec, time, and ownership contracts.
- [ ] Fill the format-specification contract register in subsystem dependency order.
- [ ] Implement an internal structural schema plus separate semantic validation.
- [ ] Provide complete valid and invalid fixtures with expected diagnostics.
- [ ] Reject unsupported versions, unknown behavior fields, invalid reference types, recursive components, illegal graph cycles, and excessive resources.
- [ ] Produce two contrasting complete audiovisual exhibits early; expand toward all PRD challenge cases.
- [ ] Reconcile prior conversation proposals into the local documents; resolve conflicts explicitly.
- [x] Complete shared document, type, reference, ValueSpec, ConditionSpec, time, and ownership contracts. Formalized in [Format Specification Rev 0.2](XZBT_0-1_Format_Specification.md).
- [x] Fill the format-specification contract register in subsystem dependency order. Document/schema and Values/conditions completed.
- [x] Implement an internal structural schema plus separate semantic validation. Schema authored in [schema/xzbt-0.1.schema.json](../schema/xzbt-0.1.schema.json), validator implemented in [tools/validate-exhibit.mjs](../tools/validate-exhibit.mjs).
- [x] Provide complete valid and invalid fixtures with expected diagnostics. See [test/fixtures/gc2/](../test/fixtures/gc2/) and [GC2 evidence](evidence/phase0/2026-09-05-gc2-format-contracts.md).
- [x] Reject unsupported versions, unknown behavior fields, invalid reference types, recursive components, illegal graph cycles, and excessive resources. Verified with 12/12 passing automated test matrix in [test/gc2-runner.test.mjs](../test/gc2-runner.test.mjs).
- [ ] Produce two contrasting complete audiovisual exhibits early; expand toward all PRD challenge cases. Minimal and full feature test fixtures created; full audiovisual reference exhibits belong to Phase 1/Phase 9.
- [x] Reconcile prior conversation proposals into the local documents; resolve conflicts explicitly. Reconciled into local format specification Revision 0.2.
**Evidence:** versioned specification/schema/fixtures and validation results. Naming a node or behavior does not close its contract.
**Evidence:** versioned specification/schema/fixtures and validation results in [2026-09-05-gc2-format-contracts.md](evidence/phase0/2026-09-05-gc2-format-contracts.md). Naming a node or behavior does not close its contract.
## 3. GC3: Resolution semantics