Studio migration to Story Source Language

Status: migration contract and source-owner inventory, 4 November 2026. The implementation now executes full-work projection, retained archives, staged adoption/restore and rollback through current owners, with real persistence fixtures. No hosted story or installed application has been migrated. The staged adoption schedule below remains an operational rollout plan; source implementation does not perform a live cutover. The language contract owns syntax and core semantics; vocabulary, queries, and protocol own the proposed standard terms, computation and effects. The core uses generic records, namespaced types, open fields, and progressive formalization; schemas are advisory by default. The mappings below use the standard vocabulary, with lossless Studio extensions for semantics outside those standard shapes.

1. The starting point

Studio already represents much of a story as structured, revisioned material. A new language should expose and complete that model while preserving its authority, not create a parallel agent memory. The current story model is version 2, with fourteen record families and a registered catalogue covering thirty-six areas of story development. Scene writing and outline operations have their own owners and receipts. A language-level graph does not by itself unify these transaction boundaries.

The product guarantees in soul.md remain the baseline: the writer directs, every visual and agent action reaches the same owner operation, Story Space is authoritative memory, exact expression and alternatives survive, and outline order determines the film. A successful migration preserves those guarantees across restarts and failed writes.

This inventory describes the source in the shared checkout at inspection time. Several files were already being edited by other sessions. It is not a qualification of an installed or deployed build. Before implementing a migration, repeat the inventory on its exact candidate commit.

2. Current owners and proposed mappings

Work and account identity

The screenplay row stores id, userId, slug, title, logline, manuscript status, setupState, genres, complexity, portfolio focusStatus/focusRank, and an activeCutId pointer. The row's comment assigns development memory to Story Space. Map the screenplay identity to the language's work identity. Preserve original IDs or a permanent bijective identity map; titles and slugs cannot become identity. Keep account ownership and authentication in the host. A document asserting an owner is not an access grant. Portfolio ranking and local navigation belong in application metadata unless an explicit portable profile covers them.

Story memory state accepts an authenticated NativeMemoryScope with storyId, writerId, and conversationId. It checks the screenplay's owner, native memory binding, and conversation ownership. Preserve these checks at every import, query, write, and receipt-recovery boundary.

Story Space core

The normative current record schema is story-domain.ts; story-catalogue.ts and story-vocabularies.ts own its optional detail vocabulary.

Every current record also carries schemaVersion, id, storyId, revision, semanticRevision, createdByOperation, createdAt, authorship, optional predecessor, and common origin, management, lifecycle, standing, interpretation, sourceRefs, dependencies, and facets. These fields must have explicit destinations or retained lossless import envelopes. It is insufficient to map only record bodies.

Important distinctions already present:

• standing is proposed, chosen, open, set-aside, or superseded; lifecycle separately distinguishes active, superseded, merged, and tombstoned.
• Origin distinguishes writer, agent, imported, researched, and derived; management distinguishes writer-managed and agent-managed material.
• Exact references are {family, id, revision}. A historical reference must never silently resolve to a current revision.
• Scope carries context/frame and optional start/end points and track; perspective carries story-world, audience, unknown, entity, or narrator, with group quantification when applicable.
• Detail values include original language-bearing text, booleans, exact references, ordered/unordered reference sets, versioned terms, decimal quantities, ranges, time expressions, and spatial coordinates. Archetype values add their own structured types.
• Source anchors use whole sources, exact code-point text intervals with quotes, normalized image regions, or time intervals. Language anchor rules must preserve those coordinate systems or explicitly translate and verify them.

Coverage of existing story vocabulary

The thirty-six registered categories already cover identity/intention; entity identity; formative background; desire/motive/stakes; inner life; voice/behaviour; character development; relationships/power; promises/dependencies; conflict; places/access; period/environment; institutions/culture; economy/technology; world rules; objects/continuity; events; in-story choices; causality; structure; plotlines; closure; knowledge/secrets; disclosure; POV/reliability; audience experience; theme; motifs; tone/rhythm; dialogue/action/sensory expression; alternatives; research/questions; authorial decisions/constraints; readings; organisation; and artifact continuity.

Treat these as optional vocabulary, not thirty-six mandatory forms. The language standard library may suggest namespaced terms and advisory schemas, while authors can introduce new concepts without first changing application code. Migration still needs a versioned mapping for every registered (catalogueId, fieldKey, value type, owner family). Unknown records and fields remain readable and preserved in the language, with validation capability reported separately. No import should coerce an unknown term into an apparently understood generic string.

The current host uses strict schemas and closed enums. A new open language cannot be enabled simply by removing these validators. Introduce a lossless extension envelope or sidecar within the single owning persistence system first, while preserving the existing known-value adapter. The adapter must report unsupported operations or render unknown content generically, rather than reject the entire readable document or discard its fields. Unknown values never confer approval, identity equivalence, executable behaviour, or permission. Authorization, host-issued revision/receipt identity, and operation preconditions stay strict regardless of advisory domain schemas.

Characters and archetypes

Character identity is an entity in the shared domain. Archetype deck values, echo values, and archetype profile add interpretation and writer-choice behaviour. Keep card identity, evidence, hand membership, accepted/set-aside choices, and custom values intact. An archetype is a reading of a person, not the definition or exhaustive psychology of that person. These can be a namespaced extension profile if the core language does not encode the product's card vocabulary.

Outline and film order

outline-film.ts owns the shared ordering/label functions. A FilmBoard has columns, cards, and branches. Cards have placement in film, alternative, or loose material; branches name fork/rejoin beats. outline-film-scenes.ts derives scene order from the board and scene-to-beat homes. Scenes without a beat retain a defined relative fallback position. Outline operations and their execution owner must remain the mutation path until replaced atomically.

Map outline elements to stable units and explicit composition/alternative membership. Persist the writer's ordering choices once. Numbering and labels are derived views; labels such as 7a.1 must not become stable IDs. A repeated portrayal of one event can have distinct presentation positions without duplicating the event's identity. Migration fixtures must include loose beats, nested alternatives, rejoin points, multiple scenes under a beat, scenes without a beat, and ties in existing positions.

Scene specification, draft, and script selection

The current typed scene specification has optional title, five optional lines (in, out, changes, who, turn), mustNot, keep, and agentNotes. Lines distinguish writer and agent attribution; writer-marked lines require the writer's words, and can retain sourceTurnId. A keep may refer to fromDraftId. Agent working notes have their own sections. Map these to specification intent/constraints, exact quoted writer evidence, and attributed interpretation. A partially developed specification is valid.

Scene stage results expose exact draft identity, number, heading, Fountain body, selected-script status, spec revision, author/time, checks, critiques, and writer verdict. Scene version storage includes immutable drafts with parent lineage and spec links. Scene rows keep inScriptDraftId; their fountain field is the selected draft's body or empty. The language must distinguish scene identity, draft identity/revision, and the composition's selected draft.

Map prose to an exact Fountain-bearing expression/draft; map spec references, lineage, checks, critic notes, and writer verdict to separately attributed records. Preserve headings exactly as the current owner represents them; do not add a duplicated slugline while rendering. Preserve whether a draft entered the script through the current first-draft policy or an explicit writer selection. The script-reading projection renders written scenes, unwritten scenes, bare beats, and out-of-film material distinctly. A language export must not accidentally erase unwritten work because only finished pages are printable.

Stored cut tables and scene-version reads also exist. Their presence does not make them the current film-order authority. Archive every retained cut manifest; reconcile it with active Script behaviour explicitly. Imported historical editions must not take over the active outline.

Sources, conversations, and media

Original chat and voice-final sources remain evidence. Do not substitute agent-produced conversation summaries or import assistant messages as writer decisions. A source can refer to an existing exact journal event without copying the whole chat into every story document. Historical source availability and conversation ownership must survive round-trip export.

Source validation verifies exact signed journal expression, historical material blocks, retained research/artifact excerpts, and finalized media manifests. Sources are immutable outside the existing Undo path; correction is represented by successor evidence.

The generic domain shape mentions image/audio/video/ink, but the current asset staging contract admits PNG, JPEG, WebP, and ink JSON, and source validation restricts admitted media to image and ink. Audio/video in the proposed language is future capability, not existing support. Preserve references and declared unavailable media; do not claim bytes were retained unless verified. Asset integrity, private access, byte bounds, and MIME verification belong in the host adapter.

Concrete adapter conventions

The implemented adapter reserves studio to urn:screenplay-company:ssl:studio:0.1. This is a proposed vendor profile identity, not a deployed registry. It preserves the complete original envelope and payload under record.extensions["studio.legacy"], including source schema version, source owner domain, original identity, original revision, source snapshot and fields. The original envelope/payload is retained as JSON text in a payload string with payloadEncoding: "application/json", or as a verified original-byte asset; it is not injected as unrestricted nested SSL numbers. This preserves source floating-point values and serialization that the new core does not admit. Normalized interoperable coordinates and quantities use exact tagged decimal/rational values. This retained envelope is the reverse adapter's fidelity witness; it is inert data and cannot grant writer authority. Standard fields are the useful interoperable view of that data. Both must be updated through one adapter transaction, or the extension must be marked stale and reverse migration refused.

Existing IDs are not already absolute URIs. Native-memory compatibility projections use the following deterministic domain-qualified identities:

work        → urn:screenplay-company:work:<encoded-story-id>
record      → <work-URI>:story-record:<encoded-record-id>
scene       → <work-URI>:scene:<encoded-scene-id>
draft       → <work-URI>:scene-draft:<encoded-draft-id>
outline     → <work-URI>:outline-record:<encoded-outline-id>
operation   → <work-URI>:<owner-domain>-operation:<encoded-operation-id>

Encoding applies to UTF-8 bytes, preserves only ASCII letters/digits and -._~, and percent-encodes every other byte with uppercase hexadecimal. No decoding or normalisation occurs during SSL identity comparison. Owner domains are distinct, so equal existing strings from different stores cannot collide. Additional source domains and split-out expressions use equally explicit domain tags. Retain a bijective identity manifest and reverse-check it. A generated expression for block b has an identity derived from its source record and block ID, never from its mutable text or display title.

The whole-work archive projection additionally observes mutable owners that have no portable revision ledger. Each owner row keeps one stable identity across reads, urn:screenplay-company:owner-row:<sha256> over the work, native table and primary key (studioWorkRowId, the same identity the work change feed reports), with exact native table/key/ID and row digest in studio.owner. Because no revision clock exists, no revision is counted or faked: an observed record's revision is a 48-bit tag of its exact projected content, so it stays the same while the record is unchanged and differs once it changes, and an exact reference never names two states. Tags carry no order; compare them for equality only. Links between observed records are snapshot references, except where a link pins an exact state (a draft's expression, spec and parent; a selection; an edition's occurrences). A scene_drafts row is itself the film.draft. Immutable screenplay expression identity uses the work, original draft ID and exact prose. Native-memory and generic SSL records retain their original revision ledgers. The complete archive identity manifest and original rows, rather than a guessed common revision number, drive reverse migration.

Specific mappings that need more than a rename:

• Existing sourceRefs become standard sources or claim/reading evidence anchors. Convert code-point text anchors directly; convert millisecond time intervals to exact reduced rational seconds. An anchor's field path must address the migrated expression body, not a former nested block offset.
• Existing dependency roles (identity, semantic-support, history, organization, appearance) remain in studio.legacy and a studio.dependencies open field with their exact refs and roles. Standard dependsOn alone does not preserve those distinctions. Freshness invalidation uses the preserved roles.
• assertion.polarity maps to story.claim.stance when meaning matches. Mode, perspective and modality are separate in the source: possible, conditional, counterfactual, obligation, and reported remain explicit studio.modality values. Never flatten them into world/asserted. Perspective group quantification and truth-basis qualifiers remain studio.perspective and studio.qualifiers when no standard field expresses them. The source field address remains studio.fieldAddress and can name a proposed registered predicate.
• Context basisStoryRevision, exact basis, ordered include/exclude/replace effects and conflicts remain studio.contextBasis / studio.contextEffects fields. Standard story.context.parent is insufficient to reconstruct a development alternative.
• Current entityKind=frame becomes story.context; person, place, object, and collective map to their matching standard kinds. An institution can be story.concept with studio.entityKind=institution; a nonhuman actor uses an explicit studio.nonhumanAgent kind. Preserve all names/aliases and entity-kind history. No subtype is inferred from prose.
• narrative-unit without a proven owning scene/beat relation stays film.unit with its declared unitKind. A draft migration must not create a second scene merely because its title matches a narrative unit.
• Material blocks remain ordered. A single text block can map directly to an expression; multiple text/reference/asset blocks retain studio.blocks with explicit expression/asset refs. Concatenation is a display option and cannot replace the ordered source representation.
• Story pages use story.page; collection arrangements use story.collection. Manually arranged boards, diagrams and ink use studio.arrangement with the preserved full placement/drawing structure. core.view is disposable and therefore cannot be the sole representation of authored layout.
• Scene spec in/out/changes/who/turn maps to film.spec.enters/leaves/change/wants/turn. Per-line attribution and writer quotations remain attached in studio.authoredLines; keeps and must-nots become story.constraint records with exact evidence and draft refs. Agent working notes remain attributed story.reading or preserved studio.agentNotes.
• Stored immutable draft identity maps to film.draft; draft number remains studio.draftNumber, while the SSL record revision tracks changes to its metadata without implying a new authored draft. Draft Fountain text becomes an exact story.expression. The expression, spec and parent links are pinned revisions.
• The active Outline derives a film.edition and film.occurrence records. Historical cuts become separately labelled historical editions; they never overwrite the current edition. A migrated first-draft selection retains studio.selectionCause=first-draft and its original receipt. New SSL draft creation alone does not select it; the adapter must explicitly represent an already-authorised selection as a separate effect in its transaction/workflow.
• Semantic reads remain story.reading, not core.derived calculations. core.derived is reserved for deterministic SSL-Q output with the query, inputs, coverage and function versions required by queries.md. Current agent-authored portraits must not be misrepresented as deterministic computation.

The native record revision is preserved as the corresponding SSL revision where identity is one-to-one; semanticRevision remains studio.semanticRevision. Split records retain exact source-to-output revision maps. A whole-work snapshot binds the fenced owner manifest, not the maximum of unrelated counters. New host revision numbers are allocated under SSL-P; adapter history retains all original clocks.

3. Operation and authority contract that migration must preserve

The story change-set owner is the authoritative write path. Requests carry operationId, expectedStoryRevision, kind, source event, exact writer quote when required, optional host-bound run, mutations with expectedRevision, and optional reading selections. It separates contribute from writer changes, verifies current finalized writer input, and admits records and their receipt in one guarded database batch. Exact-input retries recover the original receipt. Reusing an operation ID with different input conflicts.

Record preparation prevents contributions from becoming chosen decisions, claiming false origin, overwriting writer-managed material, or changing standing. It binds actual authorship and operation identity at the owner. A text file that says chosen therefore cannot be applied as an agent contribution. Trusted migration can preserve previously verified authority as imported historical evidence; it must not turn arbitrary external status into new writer consent.

The scene receipt owner has a separate idempotency domain: the stored request hash includes operation target and request, while turn cost is excluded from write identity. It verifies operation and scene/draft target on replay. The scene authority module, authenticated route scope, and native scene access boundary must all retain their effect. Similar requirements apply to outline receipts. A universal language operation must dispatch through these owners, not write their tables directly.

The initial adapter cannot advertise an all-or-nothing transaction across memory, outline, and scenes: the current owners do not expose that universal contract. Until a shared commit boundary is implemented and tested, a multi-owner plan must either be rejected as unsupported or use an explicit durable workflow reporting each confirmed receipt and any unfinished step. It must never answer with a fabricated global success receipt.

Story Undo reconstructs the inverse from the original receipt. It rejects changed targets and later dependent work instead of accepting a client-written inverse. New records are tombstoned/set aside on Undo; existing records return through a new revision. Keep the distinction between undoing an admitted operation, changing a choice now, and restoring an old document snapshot.

4. Local drafts, recovery, and export

The Discovery recovery snapshot retains page/editor state, context-change/export attempts, exact capture Undo progress, attention drafts, and hand changes. The SQLite recovery adapter binds cache entries to account and story, checks account transitions around asynchronous writes, retains the newest failed checkpoint for retry, and imposes size/expiry bounds. This is bounded local recovery, not a promise of unrestricted offline authoring or synchronization.

A language editor must preserve uncommitted source separately from confirmed state, with its base revision and original pending operation identities. Restart must restore a parse-invalid working draft without admitting it. Reconnection must look up an uncertain operation's original receipt before retry or rebase. Signing out and switching accounts must not reintroduce a previous account's pending data.

The existing story transfer request supports paged transfer and asset reads. exportStoryDomain in the story operation owner pins story and source high-water marks and exports sources, revisions, dependencies, operations, changes, reading selections, and selection history. It is a useful primitive, but not evidence of an atomic full-work snapshot across scene and outline owners. A full language archive needs an explicit snapshot manifest for each owner and a consistency protocol.

Implemented full-work capture uses one guarded D1 batch across the registered owners, then streams immutable retained rows and verified media. This supplies a coherent owner snapshot without a long-running write fence. Apply and rollback separately compare exact staged owner state, with narrow admitted-approval/execution-progress exceptions; unresolved operations remain recoverable by their original identity. A partial export must declare omitted scopes and cannot be imported as a complete reconstruction.

5. Migration stages and exit gates

The language can remain a portable source and operation protocol over the existing database indefinitely. A storage rewrite is optional; it should follow evidence that the language needs one. Avoid independent dual writes. If the host maintains both representations, one transaction or a durable outbox must record the owner write and projection work, with explicit lag and replay.

6. Required acceptance fixtures

These behavioural acceptance fixtures are mapped to executable evidence in the complete conformance inventory. The documentation itself is not test evidence.

1. A seed with only one paragraph and an unanswered question imports and exports without invented characters or structure.
2. A writer choice, agent interpretation, researched fact, character belief, and uncertain identity remain distinguishable after round trip.
3. Original multilingual text, combining characters, emoji, RTL text, whitespace, and Fountain controls retain exact expression; source anchors still select the same code points.
4. A corrected source invalidates dependent current readings while historical references remain readable.
5. Two alternative contexts share one person identity but hold incompatible claims without contaminating the main story.
6. A flashback moves in film order while world-event order and character knowledge remain unchanged.
7. Loose beats, nested branches, rejoin points, multiple scenes per beat, and scenes without a beat produce the same current Script order.
8. A scene has several drafts, an older selected draft, later critic notes and a newer specification. All identities, stale readings, keeps and writer verdicts survive.
9. A response is lost after commit. Restart resolves the original receipt, makes no duplicate draft, and does not retry under a new operation ID.
10. An operation ID reused against a different scene/draft or different content fails.
11. Undo after a later dependent change is refused with the dependency preserved; an eligible Undo creates the correct new revision.
12. Account switch during checkpoint flush cannot leak or resurrect the previous account's recovery state.
13. Interrupted migration before and after ownership-pointer switch resumes deterministically under its original migration ID.
14. Retained unsupported fields and unavailable media remain visible as such; export cannot claim completeness when their bytes or scopes are missing.
15. A host re-imports an untrusted archive claiming author approval; the archive remains imported evidence and gains no writer authority.
16. Two concurrent agents propose changes to the same base. At most the eligible change commits; the other gets explicit conflict and retains its proposal.
17. A current recovery draft is temporarily syntactically invalid; closing and reopening preserves it without replacing the last confirmed story.
18. A current exact source archive is reconstructed in an empty test account without changing authorship or losing selection history. Account ownership is deliberately rebound by the authorized importer rather than copied as a credential.

7. Resolved design and remaining implementation gates

The language proposal has selected JSON-native open records, optional namespaced definitions, advisory schemas, exact expression, pure snapshot queries and strict host-mediated effects. Language, queries, protocol, and vocabulary specify those choices. They are no longer open migration decisions.

The remaining gates are evidence and implementation work:

• Implement and verify the identity/revision mappings and lossless studio.legacy envelope above on the exact migration candidate. Exercise every registered C01–C36 value type; unknown fields remain queryable and preservable.
• Prove a whole-work snapshot fence and owner manifest across memory, outline and scenes. SSL's opaque snapshot contract does not combine these clocks automatically.
• Include all retained historical cut and scene compatibility records in a full migration archive, labelled historical and separate from current selections. Verify actual active callers again before retiring a storage path.
• Implement the host approval/import attestation in protocol §4. Preserve verified source authority as historical evidence; imported labels alone never establish new writer authority.
• Implement the selected retention/export policy using language §6 and protocol §8. Declare missing sources, filtered coverage and erased history; hashes cannot replace unavailable evidence. A full migration archive includes every still-retained source, revision, selection and receipt in its stated scope.
• Qualify the single Outline-derived edition and explicit draft-selection effects. Generic alternate-edition support must preserve Studio's current ordering and approval behaviour.
• Qualify lossless generic reading, query traversal and editing of unknown definitions. Advisory findings must not turn into global save blockers; unsupported effect semantics still fail precisely.
• The user requested the full lifecycle specification: prep.*, shoot.*, post.* and delivery.* are therefore within this proposal's scope. Existing Studio owners do not yet provide those workflows. Future production adapters require their own source inventories, interoperability profiles and qualification; there are no existing production records to claim migrated by this document.
• Run installed voice/device, restart and real writer-journey qualification after code exists. Parser, query and round-trip tests prove their respective contracts, not the whole writing experience.

Acceptance of this specification can authorize implementation planning. Migration of live work still requires the explicit cutover procedure and evidence above; documentation alone is not a migration receipt.