8.7 KiB
XZBT Format Specification 0.1
XZBT format version: 0.1
Document revision: 0.1
Status: Partial normative specification; contract completion required before dependent implementation
Related resources: PRD, decisions, verification
This document defines shared semantic decisions and tracks the contracts still needed to implement the PRD. Existing PRD examples remain design inputs; a list of supported feature names is not a complete JSON grammar. No validator or complete JSON Schema has yet been produced.
1. Format foundation
Documents are UTF-8 JSON with xzbt: "0.1", meta.id, and meta.name required. Unsupported format versions fail activation. Exhibit version and format version are separate. IDs use ^[a-z][a-z0-9_-]*$; dots delimit reference paths.
The following is a complete minimal exhibit. An exhibit that performs no audio or visual work is valid:
{
"xzbt": "0.1",
"meta": {
"id": "empty-study",
"name": "Empty Study"
}
}
Validate structure before activating resources. Follow structural validation with type, reference, graph, ownership, and resource-limit checks. Unknown fields in behavior-bearing objects are errors. Do not coerce strings to numbers or silently invent semantics for unsupported constructs.
A structurally valid minimal exhibit does not prove expressive capability. Complete audiovisual examples and invalid fixtures remain required under GC2.
2. Shared value resolution
For each supported target, evaluate:
base -> binding -> automation -> winning override -> modulation -> safety clamp
Skip stages not exposed by the target contract. A target cannot accept automation or modulation merely because it is numeric. Additive modulation is summed only where explicitly supported.
Parameters store user configuration separately from exhibit defaults. State stores simulation values separately from parameters. A property may obtain its base through ValueSpec. State is not an implicit layer overwriting every parameter.
References ordinarily read resolved values. Parameter controls read and edit stored user values, and display an override indicator when appropriate. Underlying bindings and automation continue to evaluate while masked by an override.
Override lifetime and priority are independent. Use explicit priority when supported, otherwise inherit the originating scenario's priority; equal priorities resolve by activation order. Duration scope confers no additional priority. The complete action contract must define non-scenario default priority, permitted explicit priority fields, and ordering identifiers before implementation.
On release, blend toward the current lower resolved value rather than a snapshot taken when the override started. User edits and changing bindings remain visible to that lower evaluation. Numeric release interpolation, interruptions by another override, and nonnumeric release behavior require exact contracts below.
Reject conflicting ordinary bindings and dependency cycles that cannot be evaluated under documented semantics. Do not introduce an implicit previous-frame delay to make a cycle appear legal.
Required resolution examples
| Case | Expected behavior |
|---|---|
| Bus gain is bound to activity, then directly overridden | The override supplies the pre-modulation value until release; the binding continues underneath |
| Activity is overridden and referenced by a binding | The binding observes resolved activity |
| User edits stored activity while its override is active | The stored edit persists; release approaches the updated lower value |
| Two overrides compete | Higher priority wins; equal priority uses activation order |
| Duration and scenario overrides compete | Priority and activation order decide, not scope |
| A target has legal additive modulation | Modulation follows the winning override, then the safety clamp applies |
3. Time and random evaluation
The initial logical simulation step is 1/60 second. Rendering does not own simulation time. Audio scheduling maps logical time to the audio clock with a bounded horizon.
Application pause and document visibility loss suspend logical progression and audio. Resume continues the same logical performance without a wall-clock catch-up burst. Visibility resume does not clear a user pause. Audio unlock does not replay expired sound invocations.
Random and weighted-choice ValueSpecs are sampled at the containing object's documented instantiation or invocation boundary, not every render frame. Evolving randomness belongs to modulators. Nested ValueSpec evaluation boundaries and random time sampling must be specified per construct.
Separate random streams isolate cadence, scenario instances, visual systems, sound instances, and manual sampling. Reproducibility is scoped to a runtime version, recorded numeric seed, and logical input sequence. Tests that use external or analysed signals must supply deterministic input traces.
4. Ownership and termination
Ownership propagates through nested events and actions. Scenario resources inherit the scenario owner unless the resource type allows an explicit persistent owner. Scenario-created duration overrides cannot outlive the owner, apart from their bounded release cleanup.
Persistent set changes survive scenario failure. Termination cancels future work and guarantees cleanup, including when a termination hook fails. Release work transfers to a bounded cleanup owner and ultimately disposes all temporary resources.
Condition triggers require a false condition before rearming after a successful firing. Each scenario definition may hold at most one deferred start request. Requests expire and recheck eligibility when dispatched. Exact timeout and ordering contracts remain required.
Statically check event/scenario feedback where possible and bound runtime dispatch. Resource cleanup must remain possible after the ordinary dispatch budget is exhausted.
5. Contract completion register
All rows below require work; none claims a completed implementation. Complete shared contracts before implementing dependent subsystems. Use PRD section numbers as stable lookup references.
| Contract | Existing PRD input | Required completion |
|---|---|---|
| Document/schema | 9-14, 113-116, 121 | All structural shapes, unknown-field policy, metadata extensions, size/depth limits, diagnostic paths, full internal schema |
| Values and conditions | 15-21, 33 | Operator arity and types, numerical errors, array/object literals, live versus sampled fields, seed algorithm and stream derivation |
| References and bindings | 13, 17, 31-32 | Target-capability table, instance/input scope, evaluation order, cycles, disabled bindings, exact smoothing |
| Actions and transitions | 22-30 | Fields and defaults per action, override priorities outside scenarios, target/command matrix, interrupted transitions, instance IDs |
| Audio | 34-60 | Complete recipe/component shapes, node defaults, automation timing, clamp implementation, one-shot endings and tails, unlock behavior, master protection contract |
| Cadence | 61-68 | Exact selection/cooldown/overlap fields, clocks, pool collisions, pending audio, manual sampling isolation and continuous-sample termination |
| Visuals | 69-89 | Primitive/system/behavior fields, angle and motion units, transform order, depth projection, field behavior, morph compatibility, effect approximation and limits |
| Events/scenarios | 90-102 | Trigger shapes, hooks and failure ordering, scope inheritance, deferred ordering/expiry, relative/repeated timeline semantics and termination boundaries |
| Generated UI | 103-107 | Widget compatibility, button actions, parameter validation and override display, group/control ordering |
| Runtime/library | 108-112, 117-127 | Clock/audio synchronization and stalls, import equality, update compatibility, transactions, failure recovery, persistence schema |
6. Contract template and conformance artifacts
Each construct must record its JSON shape; required and optional fields; types, units, ranges, and defaults; supported ValueSpec fields and evaluation timing; read/write namespaces; lifecycle and ownership; precedence; validation errors; runtime failure behavior; and resource costs or limits.
Supply a valid minimal example, a meaningful composition example, invalid cases with expected diagnostics, and expected semantic traces where timing or ordering matters. Two contrasting complete exhibits must exercise parameters, sound, visuals, and a temporary scenario override early in development.
Structural JSON Schema does not replace semantic validation. The internal schema and fixtures belong to 0.1 implementation work; public schema distribution and editor integration may follow later.