# Seedance upstream to ElserStudio MCP contract

This contract applies to every active module under `modules/`. The complete Seedance 2.0 v6.7.0 material is retained, but ElserStudio owns execution and canonical state.

## Authority order

1. User intent, safety, consent, rights, and explicit spend scope.
2. ElserStudio World identity and asset authority.
3. ElserStudio MCP schemas and the desktop capability-router's current capabilities.
4. Canonical Project, World, Episode, Shot, generation-task, blob, and canvas state.
5. Accepted and actually observed generation results.
6. Upstream directing, prompt, continuity, multilingual, and production guidance.
7. Upstream surface facts, examples, and defaults.

Upstream facts with dates remain useful research evidence. They never authorize a direct Provider call or override the currently registered ElserStudio model route.

## Production object mapping

| Upstream artifact | ElserStudio canonical target | MCP path |
|---|---|---|
| story state / project state | Project + active World + Episode + ordered Shots | `list_projects`, `get_world`, `get_episode`, `list_shots` |
| character/environment/prop bible | World characters, scenes, props, style and shared assets | World read/write and attachment tools |
| sequence plan | Episode and Shot order | `upsert_episode`, `replace_episode_shots` |
| clip contract | Shot fields and provider-neutral `generationContract` | `get_shot`, `update_shot` |
| reference role map | canonical World references plus explicit motion/spatial/continuity references | `assemble_shot_references`, `import_local_asset` |
| prompt spec | Shot prompt and generation request | `update_shot`, image/video submission tools |
| generation run | persistent generation task | submit/get/list/cancel/resume generation tools |
| returned take | task result with blob metadata | generation-task tools and canvas synchronization |
| continuity ledger | concrete incoming/outgoing Shot continuity state | `generationContract.continuity` through Shot tools |
| accepted episode media | Shot media bindings on the canonical canvas workflow | `sync_episode_to_canvas` |

Do not persist upstream `project-state.json`, `generation-runs.jsonl`, clip files, or a second task ledger during a live ElserStudio production. Vendored examples remain test/reference fixtures only.

## Prompt and reference compilation

- Preserve the upstream dramatic-intent, action-chain, directing-coherence, anti-slop, language, safety, and delivery reasoning.
- Pass provider-neutral prompt text and typed reference objects to MCP.
- Never fabricate or hard-code `@ImageN`, `@VideoN`, `@AudioN`, upload tokens, Provider URLs, model IDs, API fields, or credentials in canonical Shot state.
- The capability-router and Provider adapter compile the active surface syntax after MCP validation.
- World identity references outrank style, motion, camera, spatial, first/last-frame, and continuity donors for identity dimensions.
- A `spatial_guide` may constrain composition and camera but cannot replace a canonical character, scene, prop, voice, or World-style reference.

## Generation and spend

- Use asynchronous MCP submission for media generation unless the user explicitly needs a blocking single result.
- Submit independent or shared-anchor tasks as a batch after validating the whole batch.
- Submit sequential continuations one at a time after the predecessor reaches a terminal state and the accepted end state is known.
- Poll with `get_generation_tasks` until `allTerminal`; Provider task IDs and URLs are not completion evidence.
- Do not automatically retry a paid result. Apply the upstream take-review and one-variable rule, then obtain authorization for another generation when the original scope did not include it.
- For reusable generated World media, provide both `worldId` and `targetAsset`.
- For canvas-visible images, provide `projectId`; provide `canvasWindowId` only to intentionally update an existing image node.

## Research, multilingual, and professional material

- Load the vendored `api-status`, `source-registry`, platform matrix, and dated research before making historical or surface-specific claims. Verify unstable current claims externally when the user needs present-day facts.
- Preserve all English, Chinese, Japanese, Korean, Spanish, and Russian vocabulary and examples. Translate production meaning while retaining canonical names, quoted dialogue, and typed reference identity.
- Preserve professional preproduction, shot-list, continuity, color, sound, subtitles/localization, aspect-ratio, delivery, and QC guidance. These modules may produce plans and review artifacts, but may only persist fields supported by MCP.
- If MCP cannot persist a structured upstream artifact such as a take-review verdict or delivery packet, report it explicitly instead of hiding it in arbitrary JSON.

## Script boundary

Vendored scripts may validate the exact upstream snapshot, schemas, examples, vocabulary, source freshness, continuity, and prompt architecture. They may also extract a last frame from a user-authorized local test asset. They must not read ElserStudio SQLite directly, mutate production files, access credentials, call Providers, or replace MCP operations.
