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

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

Browse Source 
- 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:
Labyricorn
2026-09-05 11:38:48 -07:00
parent ca2830174f
commit e02d49a739
25 changed files with 2473 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.labyricorn/devlog/phase-zero-feasibility-and-current-stall/contents.lr
+4
View File
@@ -60,3 +60,7 @@ After that evidence is obtained, Phase 0 still needs shared document/value/refer
Phase 1, the runtime skeleton, has not started. Neither have Phases 2 through 9. There is no completed production schema, integrated audiovisual runtime, reference benchmark, or soak result. The two-hour development soak and eight-hour release soak remain later acceptance requirements.
Work stopped in accordance with the request to report problems before advancing. The next step is to obtain the remaining conditional fallback evidence, complete the Phase 0 contracts and traces, and then review the gate before beginning Phase 1. The resolved Blob-module failure does not need to be repeated unless relevant code changes.
## Development-server boundary
A dependency-free loopback server was added later for possible source-level development work. It cannot count toward Phase 0: serving the probe changes the origin, security model, and module-loading conditions. The host process reached the probe successfully, but the in-app browser could not reach that host loopback listener and returned a refused-connection error. This did not change the Phase 0 boundary or start a later phase.
.labyricorn/devlog/phase-zero-stall-recovery-and-contracts/contents.lr
+89
View File
@@ -0,0 +1,89 @@
_model: devlog-entry
---
schema_version: 1
---
title: Recovering from the Phase 0 stall and establishing shared format contracts
---
date: 2026-09-05
---
author: Labyricorn
---
summary: The Phase 0 stall has been resolved: user-assisted verification of directory-picker fallback closed the final check of GC1, and shared format contracts, a structural JSON schema, and a 12-case automated conformance test suite have completed the shared gate of GC2.
---
tags: Project Planning, Browser Testing, Shared Contracts, Phase 0
---
source_commit: ca2830174f15992f7bc2f32a9da6b4c410cab803
---
body:
Following the September 4 feasibility trials, Phase 0 was stalled pending a single outstanding observation: the application's fallback behavior when directory access was denied or cancelled. In addition, the shared declarative contracts needed by downstream subsystems had not yet been codified.
Both items have now advanced in accordance with the sequential verification policy.
## 1. Resolving the GC1 feasibility gate
Direct-file Chromium operation forbids automated agent navigation under browser tool policy, and native folder picker dialogs require human interaction. The user tested the fallback in desktop Chrome 152 on Windows 11 by invoking the directory picker on the Phase 0 probe (`file:///G:/.vibe/XZBT/prototypes/phase0/XZBT-phase0-probe.html`) and cancelling the prompt.
The browser raised an `AbortError`:
```text
Failed to execute 'showDirectoryPicker' on 'Window': The user aborted a request.
```
The probe caught the rejection cleanly via its standard error handler, recorded `directoryImport: "cancelled"`, and displayed a non-fatal notification without crashing or corrupting memory. The restored definitions for Amber Study and Blue Study, customized parameter edits (`blue-study.activity: 0.37`), and master volume (`0.19`) remained intact.
This completed the tenth and final check of **GC1: Direct-file feasibility**. All ten direct-file feasibility checks are now backed by empirical evidence recorded in `docs/evidence/phase0/`.
## 2. Formalizing shared format contracts (GC2)
With deployment feasibility established, work immediately transitioned to **GC2: Format contract completeness**. The PRD separates product intent from exact authoring contracts; building the runtime requires an unambiguous declarative grammar.
The companion [Format Specification 0.1](https://git.labyricorn.com/Labyricorn/XZBT/src/branch/main/docs/XZBT_0-1_Format_Specification.md) was expanded to Document Revision 0.2, formally defining:
* **Document and Metadata Boundaries:** Mandatory `xzbt: "0.1"` and `meta` blocks, strict regex constraints for all resource IDs (`^[a-z][a-z0-9_-]*$`), dot-delimited reference paths (`<namespace>.<id>[.<prop>]`), and a strict unknown-field prohibition (`ERR_UNKNOWN_FIELD`) across all behavior-bearing sections.
* **Primitive Type System:** Six concrete types (`number`, `integer`, `boolean`, `string`, `color`, `enum`) with an absolute prohibition on implicit type coercion. Floating-point numbers must be finite; `NaN` and `Infinity` are rejected.
* **Parameter vs. State Separation:** Parameters represent user-tunable configuration persisted in client storage and protected from direct scenario mutation via `set`. State variables represent simulation-owned transient values initialized at exhibit load.
* **ValueSpec 0.1 Grammar:** Formal definitions for literals, dynamic references, bounded random ranges (sampled strictly at instantiation or event trigger boundaries, never per-frame), weighted choices, and 13 mathematical operators across strict unary (`abs`, `negate`, `round`, `floor`, `ceil`), binary (`add`, `subtract`, `multiply`, `divide`, `min`, `max`), and ternary (`clamp`, `lerp`) arities. Division by zero includes a mandatory safe clamp to `0.0` to eliminate runtime numerical failures.
* **ConditionSpec 0.1 Grammar:** Numerical and value comparisons (`eq`, `ne`, `gt`, `gte`, `lt`, `lte`), logical combinators (`and`, `or`, `not`), and edge-triggered re-arming semantics (a trigger fires only on a `false` to `true` transition and cannot re-fire until it evaluates to `false` again).
* **Standard Diagnostic Error Codes:** A unified diagnostic vocabulary (`ERR_SCHEMA_VALIDATION`, `ERR_UNKNOWN_FIELD`, `ERR_UNSUPPORTED_VERSION`, `ERR_INVALID_ID`, `ERR_INVALID_REFERENCE`, `ERR_TYPE_MISMATCH`, `ERR_CYCLIC_DEPENDENCY`, `ERR_OUT_OF_BOUNDS`, `ERR_INVALID_OPERATOR`, `ERR_INVALID_ARITY`, `ERR_INVALID_DURATION`).
## 3. Tooling and automated conformance verification
To verify that the format specification is enforceable and machine-checkable, two foundational engineering tools were authored:
1. **Structural JSON Schema (`schema/xzbt-0.1.schema.json`):** A Draft-07 structural schema declaring root constraints, pattern properties, and component definitions.
2. **Zero-Dependency Semantic Validator (`tools/validate-exhibit.mjs`):** A native Node.js command-line validator that executes both structural schema verification and deep semantic validation, including identifier checking, type matching, boundary clamps, ValueSpec operator arity checks, reference target resolution, and DFS graph traversal for cycle detection in value bindings.
A 12-case test matrix was constructed in `test/fixtures/gc2/` containing valid minimal and full-feature exhibits alongside deliberate fault-injection fixtures. The automated test runner (`test/gc2-runner.test.mjs`) verified that all valid exhibits passed and all invalid exhibits were rejected with their exact expected error codes:
```text
--- Running GC2 Format Contract Conformance Suite ---
PASS: test/fixtures/gc2/valid-minimal.xzbt (valid as expected)
PASS: test/fixtures/gc2/valid-full-feature.xzbt (valid as expected)
PASS: prototypes/phase0/fixtures/amber-study.xzbt (valid as expected)
PASS: prototypes/phase0/fixtures/blue-study.xzbt (valid as expected)
PASS: test/fixtures/gc2/invalid-unknown-field.xzbt (correctly rejected with ERR_UNKNOWN_FIELD)
PASS: test/fixtures/gc2/invalid-unsupported-version.xzbt (correctly rejected with ERR_UNSUPPORTED_VERSION)
PASS: test/fixtures/gc2/invalid-id-syntax.xzbt (correctly rejected with ERR_INVALID_ID)
PASS: test/fixtures/gc2/invalid-reference-missing.xzbt (correctly rejected with ERR_INVALID_REFERENCE)
PASS: test/fixtures/gc2/invalid-type-mismatch.xzbt (correctly rejected with ERR_TYPE_MISMATCH)
PASS: test/fixtures/gc2/invalid-cyclic-bindings.xzbt (correctly rejected with ERR_CYCLIC_DEPENDENCY)
PASS: test/fixtures/gc2/invalid-out-of-bounds.xzbt (correctly rejected with ERR_OUT_OF_BOUNDS)
PASS: test/fixtures/gc2/invalid-operator-arity.xzbt (correctly rejected with ERR_INVALID_ARITY)
Results: 12 passed, 0 failed out of 12 total tests.
GC2 Contract Completeness Conformance: ALL TESTS PASSED.
```
## Current state of Phase 0
Phase 0 is active and making concrete forward progress:
* **GC1:** 100% Passed.
* **GC2:** Shared contracts, structural schema, validator, and test suite 100% Verified. Subsystem-specific schemas (audio node graphs, visual passes) will follow in dependency order with their respective phases.
* **Outstanding Phase 0 Gates:**
* **GC3:** Shared Value Resolution Semantics and deterministic trace test suites (`base -> binding -> automation -> winning override -> modulation -> safety clamp`).
* **GC4:** Logical Clock (60 Hz fixed tick) and PRNG Stream Isolation contracts.
* **GC5:** Ownership Hierarchy and Failure Cleanup contracts.
In accordance with project principles, **Phase 1 (Runtime Skeleton) has not started** and will only begin once the remaining Phase 0 shared contracts and traces are fully specified and verified.