Conformance, diagnostics and adoption gates
1. Capability levels
These are independent capabilities, not a hierarchy requiring every department to install everything.
| Capability | Minimum promise |
|---|---|
| Preservation reader | Retain exact decoded content and unknown values; open unsupported content safely with diagnostics |
| SSL core reader/writer | Structural syntax/identity/value/namespace rules; lossless semantic round-trip and partial coverage |
| Definition-aware reader | Pinned optional definitions, advisory checks, generic fallback and explicit refinement |
| SSL-Q 0.1 | Exact supported query operators/functions, typed unknown results, access filtering, reproducible snapshot computation |
| SSL-P 0.1 | Atomic admitted operations, exact authority/digest binding, conflicts, original receipt recovery and durable restart |
| Story/film profile | Scoped claims, ordered edition expansion, exact screenplay expression and draft/choice distinctions |
| Production values/profile | Comparable clocks, exact rates/units, lifecycle identities, profile-specific readiness |
| Format adapter | Named format/version, tested mappings, original payload preservation and explicit loss report |
An implementation advertises exact capabilities and limits. It cannot claim SSL-P by storing arbitrary change envelopes without executing its guarantees. Support for an unknown record kind means preservation/query support, not understanding its meaning. No conformance level certifies story quality or industry adoption.
2. Diagnostic contract
A diagnostic has code, severity, message, optional record:ExactRef, path (field path), sourceRange and related:ExactRef[]. Severity: info, warning, error. An error concerns a named requested operation or invalid structural unit; it need not prevent opening the whole package. Diagnostics remain separate from authored text.
| Code | Expected scope/effect |
|---|---|
| invalid-json / duplicate-key / invalid-unicode / invalid-number | Retain raw input; parsed core conformance unavailable until repaired |
| invalid-envelope / invalid-reference / duplicate-revision | Structural error; no authoritative import of affected package |
| missing-namespace | Structural term identity unresolved; preserve package, offer binding repair |
| unknown-kind / unknown-field | Optional information only; storage and generic query allowed |
| unknown-tag / unsupported-capability | Preserve; only dependent interpretation/effect unsupported |
| dangling-reference | Complete-scope finding; no fabricated target, unrelated content remains usable |
| unavailable-reference | Partial/access-filtered state; reveal no private existence information |
| definition-mismatch / conflicting-definition | Advisory unless explicitly selected operation depends on it |
| stale-evidence / ambiguous-anchor | Keep exact old reference; do not retarget or rewrite automatically |
| conflict / operation-id-reused | Reject entire proposed atomic write, preserve draft |
| unsupported-atomic-scope | Current owner cannot atomically apply the requested batch |
| incomplete-query / limit-exceeded / type-error / overflow | Explicit incomplete/failed calculation; no complete claim |
| duplicate-occurrence / unresolved-draft / missing-asset | Profile readiness finding; work remains readable |
| lossy-export | Exact omissions/conversions reported; cannot claim complete round-trip |
A consumer cannot collapse unknown, unsupported or conflict to false/empty/success. Strictness protects a specific promise: syntactic identity, precision, writer authority, transactional effects or delivery fidelity. Creative discovery remains permissive.
3. Normative behavioural vectors
Each row states an input situation and required observable result. These are the acceptance contract for implementations. The implementation map links them to executable suites; the verification record records actual results and remaining release qualification.
| ID | Input | Required result |
|---|---|---|
| C01 | Minimal work with one unclassified fragment | Save/read/query without mandatory story fields |
| C02 | Undeclared local.futureConcept kind with local namespace bound | Preserve and generic render; no compilation block |
| C03 | New optional field unknown to older reader | Survives read/write including nested values |
| C04 | Existing record later bound to definition with missing recommended property | Binding succeeds with advisory finding; no content coerced |
| C05 | Incompatible new definition revision | Old uses retain old pin; explicit migration/new term required |
| C06 | Duplicate JSON key / lone surrogate / unsafe integer / malformed known ref | Structural diagnostic; raw preservation; no silent repair |
| C07 | CRLF, Telugu, combining character, emoji, quote and backslash in expression | Exact decoded scalar sequence preserved after JSON round-trip |
| C08 | Text anchor offsets match scalar length but wrong quote | Anchor finding; no evidence attestation |
| C09 | Two same-named characters; rename one | Stable IDs; exact dialogue never auto-renamed |
| C10 | Accepted portrayal of a false character belief | Choice stays distinct from world truth; context/perspective retained |
| C11 | Unapproved draft suggests a character trait | Attributed reading about that draft, no automatic canon |
| C12 | Flashback / repeated event / alternative ending | Event identity stable; presentation occurrences distinct; context explicit |
| C13 | Complete vs partial export missing source | Dangling vs unavailable; neither implies delete or false |
| C14 | Two differently filtered packages from one snapshot | Same base snapshot allowed; different projection digests |
| C15 | Edition references beat with two occurrences | Expand in array order; direct duplicate occurrence produces finding |
| C16 | Export root exact ref with live children; children later change | Frozen export reproduces recorded exact closure, not later heads |
| C17 | Delete then alias then restore | Old refs stable; restore only same identity from prior non-tombstone |
| C18 | Unknown custom tag used only as opaque data | Retain; raw query works; dependent unsupported calculation reports it |
| Q01 | Query draft-scenes fixture | Exact rows in accompanying expected file, complete under fixture scope |
| Q02 | Known false AND unknown; true OR unknown | false; true respectively |
| Q03 | Missing/null/false/empty array/unknown | Distinct inspectable values/states |
| Q04 | Unknown numeric cost within sum | Unknown total, optional labelled known subtotal; no false complete amount |
| Q05 | Empty count/sum/min | 0 / integer 0 / missing respectively |
| Q06 | Filter depends on missing value | Excluded unresolved row and incomplete result |
| Q07 | Graph cycle and maxDepth boundary | Terminate; visited revisions once; depth exclusion marks truncated |
| Q08 | Private node referenced from visible material | Filter before resolve/count; no private title/existence leakage |
| Q09 | New scene added after cached count | Snapshot/collection dependency invalidates cache |
| Q10 | Mixed currency/unit/unsupported function | Explicit error/unsupported, no implicit conversion |
| Q11 | Equal string values, different record order | Deterministic root/sort/tie semantics; bytes never locale-dependent |
| Q12 | Parameter text contains SQL/JS/tool instructions | Literal data, no execution |
| P01 | Same operation ID + same body after lost response | Original durable result, no second effect |
| P02 | Same operation ID + different body | operation-id-reused |
| P03 | Two agents revise head 3 | One commit; other conflict, draft preserved |
| P04 | Two absence-based booking proposals create disjoint records | requireCurrentSnapshot makes second stale proposal conflict |
| P05 | Proposal approval then changed payload/base | Reject mismatched attestation; no silent rebase |
| P06 | Batch includes invalid/unauthorised second change | Nothing applied |
| P07 | JSON claims writer/approved | No authority granted by the content |
| P08 | Unknown effect with known data | Reject dependent operation; readable story retained |
| P09 | Offline account switch/restart | Queue retains original work/account, no cross-account submission |
| P10 | Undo after intervening edit | Compensating proposal or explicit conflict; no erased newer work |
| P11 | Create definition + bind existing record in same batch | Staged refs resolve; atomic receipt; original fields unchanged |
| P12 | Existing namespace rebound to different URI | Conflict; no reinterpretation of stored terms |
| L01 | Same person as character and performer | Separate identities linked by casting |
| L02 | Story location vs filming venue vs media clock | Separate entities; no silent equivalence |
| L03 | 120 frames at 24000/1001 | Exactly 1001/200 seconds; no float drift |
| L04 | Different rates or clocks | Explicit conversion/sync or unknown; no direct frame-number comparison |
| L05 | Missing media in valid editorial plan | Metadata read/query succeeds; final render readiness fails |
| L06 | Unknown VFX/effect extension through unsupported adapter | Preserve sidecar/original and report loss; no claimed rendered fidelity |
| L07 | Proxy/transcode replaces original | Separate asset identity/digest and lineage; source preserved |
| L08 | Call sheet generated but not sent | No distribution receipt claimed |
| L09 | Production rights status field says cleared without evidence | Unverified assertion; no legal/host permission inferred |
| L10 | Drop-frame label boundary / midnight / speed ramp | Supported exact conversion tested, day offset explicit, unknown ramp preserved |
| L11 | 30000/1001 indexes 1799, 1800, 17982 | Labels 00:00:59;29, 00:01:00;02, 00:10:00;00; reject 00:01:00;00 and ;01 |
| L12 | 60000/1001 indexes 3600, 35964 | Labels 00:01:00;04 and 00:10:00;00 |
4. Supplied fixtures and checks
examples/minimal.story.json shows the smallest useful fragment. examples/lifecycle.story.json follows synthetic story material through a breakdown, shot, take, clip and delivery description, with an undefined custom kind and a pinned local definition. All media is deliberately unavailable. It is a representation fixture, not a rendered film or approved story.
examples/formalise.proposal.json shows defining a term and binding an existing record without rewriting it. examples/draft-scenes.query.json and its expected result specify a deterministic query example.
verify_examples.py is a limited specification-fixture checker, not an SSL implementation. It checks JSON lexical restrictions, core envelope/IDs/refs/heads, terms, known tags, dynamic-kind round-trip, exact expression preservation and selected negative structural vectors. It does not execute SSL-Q, SSL-P, profile readiness, authentication, receipt persistence or media conversions. A passing report must retain this distinction.
Run from repository root:
python3 docs/design/story-source-language/verify_examples.py
pnpm project:render
pnpm project:check
The independent review records specification issues and their disposition. Production verification begins with the gates below.
5. Implementation and migration gates
- Core: two independent reader/writer implementations exchange the corpus, including unknown extension values, malformed input recovery, Unicode and byte assets. Establish minimum limits and diagnostics.
- Queries: execute Q vectors and differential tests across implementations; measure large snapshots/joins/traversals, permission filtering, exact arithmetic and cache invalidation.
- Protocol: persistent transaction/receipt tests under process termination, delayed replies, retries, concurrent writes, partial permissions, account switching, no-save and Undo. Mock only external boundaries; use real persistence.
- Current Studio adapter: qualify the owning source mappings in migration.md; preserve exact text, decisions, alternatives, source anchors and separate revision clocks. Reconcile every mismatch before a per-work cutover.
- Reading/editing: visually inspect exact expressions and original positions through edits; verify keyboard, voice and installed restart journeys on the exact candidate when UI/runtime changes exist.
- Lifecycle exchange: one real planning→shoot→edit→delivery pilot, with originating tool owners checking semantic mapping and every lossy field. Verify rational time, offsets, audio sync, nested edits and actual media.
- Public 1.0: independent adoption evidence, stable namespace and licence governance, versioned registries, reproducible conformance suite, security review, documented limits and backwards compatibility policy.
No migration follows merely from this document passing a Markdown/fixture check. The reviewed design now has the runtime and desktop consumer described in implementation; installed qualification and live migration remain separate from source verification. Future failures refine the specification and its profiles without forcing abandonment of existing creative material.