feat(phase0): complete shared contracts and milestone plan
This commit is contained in:
@@ -34,3 +34,7 @@ The automated test runner executed 12 tests covering valid exhibits and delibera
|
||||
|
||||
The shared contracts portion of **GC2: Format Contract Completeness** is satisfied. The schema, validator, and test suite provide a deterministic foundation for Phase 1 runtime loading and validation.
|
||||
Subsystem-specific schemas and contracts (audio graphs, visual systems, scenarios) will be filled in dependency order alongside their respective phases.
|
||||
|
||||
## Revision 0.3 reconciliation addendum
|
||||
|
||||
GC3 review found that the draft BindingSpec used `from`/`to`/`transform`, conflicting with the PRD's canonical `source`/`target`/`scale`/`offset`/`clamp` fields. Revision 0.3 corrected the schema, validator, and affected fixtures to the PRD vocabulary and added `when` plus exact smoothing semantics. The same 12-case GC2 matrix was rerun as part of the 27-test combined Phase 0 suite and still passed with zero failures. See the [GC3–GC5 evidence](2026-09-05-gc3-gc5-contracts.md) for the reconciliation rationale and combined command.
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
# Phase 0 GC3–GC5 shared contract evidence
|
||||
|
||||
**Result:** Passed for Phase 0 shared resolution, clock/PRNG, and ownership/failure contracts
|
||||
**Scope:** Deterministic contract models and validation; not production runtime, real-time audio integration, or soak acceptance
|
||||
**Format specification:** Revision 0.3
|
||||
|
||||
## Contract reconciliation
|
||||
|
||||
The GC2 draft schema used `from`, `to`, and `transform` for ordinary bindings, while PRD section 32 already defined `source`, `target`, `scale`, `offset`, and `clamp`. No production runtime exists and no released exhibit depends on the draft vocabulary. Revision 0.3 adopts the PRD fields, sets `smoothing` default to `0ms`, rejects the draft names as unknown fields, and migrates the conformance fixtures. The complete GC2 matrix still passes.
|
||||
|
||||
## GC3 — resolution semantics
|
||||
|
||||
The normative contract now defines:
|
||||
|
||||
- shared target capabilities and safety clamps;
|
||||
- same-tick topological dependency evaluation;
|
||||
- exact binding transformation, conditional disabling, and one-pole smoothing;
|
||||
- override scope, priority, activation sequence, runtime IDs, and masking;
|
||||
- easing equations, attack/release behavior, interruption, and dynamic release destinations;
|
||||
- diagnostics for conflicts, cycles, unsupported targets, invalid transitions, and bounds.
|
||||
|
||||
The executable model and trace fixture verify direct bus overrides, parameter overrides feeding downstream bindings, preserved user edits, priority/scope competition, masked automation, post-override modulation, safety clamping, smoothing, interruption, conflicts, cycles, unsupported targets, and rejected draft aliases.
|
||||
|
||||
## GC4 — time and reproducibility
|
||||
|
||||
The normative contract fixes a `1/60s` logical step, eight ticks per browser turn, a `250ms` accepted wall-time limit, a `100ms` audio horizon, composable pause reasons, and unlock/resume alignment. Earlier one-shots are skipped at unlock; still-owned continuous audio aligns to current logical state with a `20ms` ramp.
|
||||
|
||||
Seed derivation is fixed to FNV-1a-32 plus SplitMix32 state expansion and `xoshiro128**`. Known vectors lock the implementation. Tests compare 60 Hz and 120 Hz render drivers, bound a one-second stall, preserve explicit pause across visibility restoration, verify unlock scheduling decisions, isolate manual sampling, and use a deterministic audio-analysis fixture.
|
||||
|
||||
The audio unlock test is a scheduling-decision model. It does not claim that future Web Audio nodes already implement the mapping or anti-click ramp. The GC1 browser evidence separately establishes user-unlocked audio and AudioContext suspend/resume in the direct-file environment. Combined synchronization must be repeated during audio integration.
|
||||
|
||||
## GC5 — ownership and failure
|
||||
|
||||
The normative contract fixes inherited scenario ownership, termination hook selection and allowed actions, persistent-state behavior, a five-logical-second cleanup bound, condition rearming, one deferred request per definition, five-minute default expiry, deterministic deferred ordering, a 1024-unit ordinary dispatch budget, and a separate 256-action termination-hook limit.
|
||||
|
||||
The lifecycle model verifies nested ownership, bounded override release, persistent state after critical failure, startup and termination-hook failures, condition rearming, deferred deduplication/expiry/eligibility ordering, bounded feedback, cleanup outside the ordinary budget, and 30 repeated completion/cancellation/failure cycles returning resource counts to zero.
|
||||
|
||||
## Verification performed
|
||||
|
||||
```text
|
||||
node --test test/gc2-runner.test.mjs test/gc3-resolution.test.mjs test/gc4-time-random.test.mjs test/gc5-lifecycle.test.mjs prototypes/phase0/audio-probe.test.mjs
|
||||
```
|
||||
|
||||
Result: **27 tests passed, 0 failed**.
|
||||
|
||||
Artifacts:
|
||||
|
||||
- `tools/gc3-resolution-model.mjs`
|
||||
- `test/fixtures/gc3/resolution-traces.json`
|
||||
- `test/gc3-resolution.test.mjs`
|
||||
- `tools/gc4-time-model.mjs`
|
||||
- `test/fixtures/gc4/deterministic-signals.json`
|
||||
- `test/gc4-time-random.test.mjs`
|
||||
- `tools/gc5-lifecycle-model.mjs`
|
||||
- `test/gc5-lifecycle.test.mjs`
|
||||
|
||||
These are Phase 0 contract oracles. Production implementations must pass equivalent traces with their actual resolver, scheduler, Web Audio nodes, event/scenario director, and resource counters.
|
||||
Reference in New Issue
Block a user