@pouchy_ai/world-sdk 0.15.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # @pouchy_ai/world-sdk
 
+## 0.18.0
+
+- `createApprovedExport({ version: 2 })` — the V2 production hand-off: a
+  synopsis, character notes, an episode split, the beats where the plot moved,
+  committed relation changes, and where the run diverged from its story.
+- **Your existing calls do not change.** `version` defaults to 1, and omitting
+  it sends no `version` at all, so a caller written before this release receives
+  a byte-identical V1 export.
+- **V1 is frozen.** `exportId` is a content hash you may be keying on for
+  idempotency; nothing was added to V1, no key was reordered in its canonical
+  string, and its `approvedscript1` domain prefix is unchanged. Golden vectors
+  generated before V2 existed hold the line.
+- `ApprovedScriptExportRow.content` is now a union discriminated on
+  `contractVersion`. **Narrow before reading version-specific fields** — if you
+  read `content.synopsis` without checking, TypeScript will now tell you. A
+  stored row keeps the version it was written with, forever; nothing is
+  migrated.
+- The two contracts hash under separate domains, so one approval exported both
+  ways yields two different, individually stable ids. That is correct: they
+  carry different content.
+- An unrecognised `version` is a **400**, not a quiet fall back to 1 — a caller
+  who believes they asked for V2 must not silently ship against V1.
+- Every V2 field is derived from committed material and **no model is called**.
+  `synopsis` is assembled from scene headings rather than written; a character
+  note quotes only an evidence-origin line; `episodes` is a mechanical split at
+  a fixed size, not an editorial judgement; `relationChanges` carries the
+  evidence layer's own wording rather than a role pair parsed out of prose.
+- A rejected scene stays rejected: `keyMoments` and `relationChanges` cover only
+  turns belonging to surviving scenes. `divergence` and `lineage` are facts
+  about the run and are not filtered.
+- `deriveStoryPackageCandidate` takes **version 1 exports only** and refuses a
+  V2 export with 422. It is the one path from an export into published canon,
+  and which V2 fields may become canon has not been decided.
+- `world.script_approved` webhooks gain `contractVersion`. Still identifiers and
+  lineage only — never the script.
+
+## 0.17.0
+
+- `scanConsistency({ layers })` — opt into the MODEL-ASSISTED layer: suspicions
+  the deterministic checks cannot prove.
+- **Your existing calls do not change.** Without `layers` the response is
+  byte-identical to 0.16.0 — no new keys, and zero model calls server-side.
+- **Suspicions arrive in `modelAssistedFindings`, never in `findings`.**
+  `WorldConsistencyFindingCode` is frozen. If you test
+  `severity === 'blocking'` over `findings`, that check keeps meaning exactly
+  what it meant; model-assisted severity has no `blocking` member at all.
+- Three gates, all required: a server flag, a declaration on the published world
+  revision, and `layers`. `modelAssistedNote` tells you which one was shut.
+- Findings are `potential` until a person decides. `findingId` is stable across
+  scans for the same judgement — derived from the code and the server-normalised
+  evidence, not from the model's wording — so a dismissal sticks.
+- At most five model calls per scan, no retry, a wall-clock deadline, and
+  `modelAssistedNote: 'incomplete'` when the budget stopped it early. Rate
+  limited fail-closed: one scan per minute per project.
+- `suspected_cross_ip_contamination` is an editorial opinion even once
+  confirmed. It is not evidence of isolation and should not gate a build, block
+  an export, or reject content.
+
+## 0.16.0
+
+- `scanConsistency()` — what a world's own record proves about itself. Ten
+  deterministic findings, each a comparison between committed facts and the
+  pinned story package. Read-only: it commits nothing, asks no model, and
+  repairs nothing.
+- **`code` is a closed set that may grow.** A published member is never removed,
+  renamed, or widened in meaning; a criterion found to be wrong is deprecated
+  and replaced beside it. Handle an unknown code as informational rather than
+  failing on it — that is what makes a minor bump safe to take.
+- **Read `coverage` before trusting an empty `findings`.** Some checks read
+  fields older ledger rows do not carry, and those entries are counted there
+  rather than skipped in silence. A clean report with non-empty coverage is
+  clean about less than the whole world.
+- `incomplete` is a status, not an empty result: the walk is capped, a `cursor`
+  comes back, and the state- and chain-level checks do not run on a partial
+  walk. `entriesScanned` stays honest even once `findingsTruncated` is true.
+- Rate limited on two axes (project and IP, 30/min each, both required).
+  `status: 'rate_limited'` arrives with HTTP 429 and `retryAfterSec`. If the
+  shared limiter is unreachable the scan still runs — a read-only diagnostic
+  should not vanish when a world is being investigated.
+
 ## 0.15.0
 
 - `getProgress()` — where a story is and whether it can go on, as a DERIVED

package/README.md

@@ -52,7 +52,7 @@ directions a beat could take, then commit the one the player picked. Off unless
 the world's published revision declares it; the `envelope` is server-side only.
 
 **Reading** — `getWorldState`, `getProgress`, `getTurn`, `listTurns`,
-`listTurnsSince`, `replayLedger`, `replayLedgerToEnd`.
+`listTurnsSince`, `replayLedger`, `replayLedgerToEnd`, `scanConsistency`.
 
 **Which credential does what.** This matters more than it looks: one of them
 expires within the hour.
@@ -161,11 +161,27 @@ copies, and `prune` — the one call here that deletes — refuses without
 
 **Production hand-off** — `createApprovedExport`, `listApprovedExports`,
 `deriveStoryPackageCandidate`. An approved editorial draft becomes a versioned
-`ApprovedScriptExportV1` carrying the whole chain: original story package →
-world instance → ledger range → evidence draft → editorial draft → reviewer.
-Idempotent on content, so replaying an export is a no-op. The Story Package
-candidate is validated and *returned*; publishing it is a separate act by a
-person, and only evidence-origin material becomes canon.
+approved script export carrying the whole chain: original story package → world
+instance → ledger range → evidence draft → editorial draft → reviewer.
+Idempotent on content, so replaying an export is a no-op.
+
+`version` picks the contract and **defaults to 1**. `ApprovedScriptExportV1` is
+frozen: its `exportId` is a content hash integrators key on, so nothing is added
+to it, ever. `version: 2` adds what a production workflow needs beyond the
+scenes — a synopsis assembled from scene headings, character notes quoting only
+committed lines, a mechanical episode split, the beats that completed a story
+node, committed relation changes, and where the run diverged from its story. All
+of it derived from committed material; **no model is called for any of it**. The
+two contracts hash under separate domains, so one approval exported both ways
+yields two different, individually stable ids. `content` is a union — narrow on
+`contractVersion` before reading version-specific fields, and expect an
+unrecognised `version` to be a 400 rather than a quiet fall back to 1.
+
+The Story Package candidate is validated and *returned*; publishing it is a
+separate act by a person, and only evidence-origin material becomes canon. It
+takes **version 1 exports only** and refuses a V2 export with 422 — it is the
+one path from an export into published canon, and which V2 fields may become
+canon has not been decided.
 
 **Editorial layer** — `createEditorialDraft`, `getEditorialDraft`,
 `listEditorialDrafts`, `setEditorialStatus`, `decideEditorialScene`,

package/dist/index.d.ts

@@ -4,7 +4,7 @@
  *  a project is running — which is exactly the field you reach for when a
  *  customer's integration behaves like an older SDK than they say they have.
  *  It sat at '0.1.0' for eight releases before anything compared the two. */
-export declare const WORLD_SDK_VERSION = "0.15.0";
+export declare const WORLD_SDK_VERSION = "0.18.0";
 export declare const DEFAULT_BASE_URL = "https://pouchy.ai/v1";
 /** One direction a beat could take. The WHOLE of what a deliberation shows a
  *  player: no reasoning, no role secrets, no simulated effects, no scores. */
@@ -528,39 +528,128 @@ export interface WorldDrainReport {
     blocked: number;
     saturated: boolean;
 }
-/** The production hand-off (Batch 7). Every line keeps the origin the SERVER
- *  verified: `evidence` with the turn it came from, or `suggestion` because
- *  nothing committed matched it — whatever the model claimed. A suggestion is
- *  never laundered into a fact downstream. */
+/** The production hand-off, version 1 (Batch 7) — FROZEN. Every line keeps the
+ *  origin the SERVER verified: `evidence` with the turn it came from, or
+ *  `suggestion` because nothing committed matched it, whatever the model
+ *  claimed. A suggestion is never laundered into a fact downstream.
+ *
+ *  Frozen means frozen: `exportId` is a content hash, integrators key on it for
+ *  idempotency, and a field added here would change the id of every export
+ *  minted from an approval that was already exported. New material goes to V2. */
+export interface ApprovedScriptExportContentV1 {
+    contractVersion: 1;
+    exportId: string;
+    title: string;
+    lineage: Record<string, unknown>;
+    review: {
+        reviewer: string;
+        approvedAt: string;
+        sceneDecisions: Record<string, unknown>;
+    };
+    characters: Array<{
+        roleId: string;
+        storyRoleId?: string;
+        lines: number;
+    }>;
+    scenes: Array<Record<string, unknown>>;
+    stateChanges: Array<{
+        summary: string;
+        sourceTurnId: string;
+    }>;
+    suggestionRatio: number;
+    exportDigest: string;
+}
+/** Version 2 (Batch 10) — what a production workflow needs beyond the scenes.
+ *
+ *  Every added field is DERIVED from material the pipeline already committed;
+ *  no model is called to produce any of it. In particular `synopsis` is
+ *  ASSEMBLED from the surviving scene headings rather than written, and a
+ *  character note quotes only an evidence-origin line.
+ *
+ *  Declared field by field rather than extending V1. The two contracts hash
+ *  under separate domains (`approvedscript1` / `approvedscript2`), so one
+ *  approval exported both ways yields two different, individually stable ids —
+ *  which is correct, since the two carry different content. */
+export interface ApprovedScriptExportContentV2 {
+    contractVersion: 2;
+    exportId: string;
+    title: string;
+    lineage: Record<string, unknown>;
+    review: {
+        reviewer: string;
+        approvedAt: string;
+        /** Whether `approvedAt` was stamped when the draft entered `approved`, or
+         *  stood in from the row's last-touch time because it predates the stamp. */
+        approvalTimeSource: 'stamped' | 'legacy_updated_at';
+        sceneDecisions: Record<string, unknown>;
+    };
+    characters: Array<{
+        roleId: string;
+        storyRoleId?: string;
+        lines: number;
+    }>;
+    scenes: Array<Record<string, unknown>>;
+    stateChanges: Array<{
+        summary: string;
+        sourceTurnId: string;
+    }>;
+    suggestionRatio: number;
+    /** Scene headings in order. Assembled, not authored. */
+    synopsis?: string;
+    characterNotes?: Array<{
+        roleId: string;
+        storyRoleId?: string;
+        lines: number;
+        sceneIds: string[];
+        /** Their first COMMITTED line. Absent when they only ever spoke suggested
+         *  lines — a model's connective sentence must not read as characterisation. */
+        firstLine?: string;
+    }>;
+    /** A MECHANICAL split at a fixed number of scenes, not an editorial one: a
+     *  reproducible starting point for a producer to move. */
+    episodes?: Array<{
+        episodeId: string;
+        title: string;
+        sceneIds: string[];
+        synopsis: string;
+    }>;
+    /** Beats that completed at least one story node — where the plot moved. Not
+     *  "moments somebody found dramatic": that judgement stays a person's. */
+    keyMoments?: Array<{
+        sourceTurnId: string;
+        seq: number;
+        completedNodeIds: string[];
+        summary: string;
+    }>;
+    /** Committed `set_relation` changes, in the evidence layer's own wording and
+     *  with the turn they came from. Not parsed back into a role pair: inventing
+     *  structure from prose is the guessing this pipeline reserves for people. */
+    relationChanges?: Array<{
+        summary: string;
+        sourceTurnId: string;
+    }>;
+    /** Where the run stands against the story it started from. Facts only — a
+     *  node never completed, or a branch condition reached. Never what "should"
+     *  have happened. */
+    divergence?: Array<{
+        kind: 'unresolved_objective' | 'branch_reached';
+        nodeId?: string;
+        branchId?: string;
+        description: string;
+    }>;
+    exportDigest: string;
+}
+/** Both contracts, discriminated on `content.contractVersion`. Narrow before
+ *  reading anything version-specific; a stored row keeps the version it was
+ *  written with, forever. */
+export type ApprovedScriptExportContent = ApprovedScriptExportContentV1 | ApprovedScriptExportContentV2;
 export interface ApprovedScriptExportRow {
     exportId: string;
     draftId: string;
     editorialId: string;
     worldInstanceId: string;
     environmentId: string;
-    content: {
-        contractVersion: number;
-        exportId: string;
-        title: string;
-        lineage: Record<string, unknown>;
-        review: {
-            reviewer: string;
-            approvedAt: string;
-            sceneDecisions: Record<string, unknown>;
-        };
-        characters: Array<{
-            roleId: string;
-            storyRoleId?: string;
-            lines: number;
-        }>;
-        scenes: Array<Record<string, unknown>>;
-        stateChanges: Array<{
-            summary: string;
-            sourceTurnId: string;
-        }>;
-        suggestionRatio: number;
-        exportDigest: string;
-    };
+    content: ApprovedScriptExportContent;
     createdAt: string;
     createdBy: string;
     deliveredAt?: string;
@@ -641,6 +730,107 @@ export interface WorldClientOptions {
      *  default is generous on purpose, and lower is usually wrong. */
     timeoutMs?: number;
 }
+/** What a world's own record proves about itself. World API 1.19.
+ *
+ *  DETERMINISTIC ONLY. Every finding is a comparison between committed facts
+ *  and the story package the instance pins — never a judgement about writing.
+ *  Nothing here repairs anything, and nothing here is a suggestion.
+ *
+ *  `code` is a CLOSED set that may GROW. A published member is never removed,
+ *  renamed, or widened in meaning; a criterion later found to be wrong is
+ *  deprecated and replaced beside it. So handle an unknown code as
+ *  informational rather than failing on it — that is what makes a minor bump
+ *  safe to take. */
+export type WorldConsistencyFindingCode = 'revision_mismatch' | 'ledger_drift' | 'ledger_missing_entries' | 'unrecorded_beat_claim' | 'orphan_branch_reference' | 'node_prereq_violation' | 'effect_without_grant' | 'flag_schema_violation' | 'relation_change_without_cause' | 'verbatim_secret_disclosure';
+export interface WorldConsistencyEvidence {
+    turnId?: string;
+    seq?: number;
+    roleId?: string;
+    sceneId?: string;
+    nodeId?: string;
+    branchId?: string;
+    flagKey?: string;
+    effectKind?: string;
+    /** Only on verbatim matches, and only the matched fragment — never a line. */
+    quote?: string;
+    /** Passed through from a committed rejection AS EVIDENCE. It is not this
+     *  finding's classification; the two vocabularies stay separate. */
+    ledgerRejectionCode?: string;
+}
+export interface WorldConsistencyFinding {
+    code: WorldConsistencyFindingCode;
+    layer: 'deterministic';
+    status: 'proven';
+    severity: 'blocking' | 'warning' | 'info';
+    /** Never empty. A finding nobody can check is an accusation. */
+    evidence: WorldConsistencyEvidence[];
+}
+/** What a check could NOT examine. Read this before trusting an empty
+ *  `findings`: a clean report with non-empty coverage is clean about less than
+ *  the whole world. Absence of a finding is not proof of absence. */
+export interface WorldConsistencyCoverage {
+    code: WorldConsistencyFindingCode;
+    skipped: number;
+    reason: 'evidence_field_absent' | 'scan_incomplete';
+}
+/** The MODEL-ASSISTED layer. World API 1.20.
+ *
+ *  A SEPARATE closed set from `WorldConsistencyFindingCode`, which stays frozen
+ *  as the deterministic vocabulary. Keeping them apart is not tidiness: code
+ *  written against 1.19 reasonably does `if (f.severity === 'blocking') fail()`
+ *  over `findings`, and a suspicion about a character's voice must never be
+ *  able to fail that build. Suspicions arrive in their own array, and their
+ *  severity has no `'blocking'` member at all.
+ *
+ *  These are judgements, not proofs. Nothing here should gate a merge, block an
+ *  export, or reject content — `suspected_cross_ip_contamination` least of all:
+ *  even confirmed it is an editorial opinion, not evidence of isolation. */
+export type WorldModelAssistedFindingCode = 'suspected_canon_conflict' | 'suspected_revival' | 'suspected_persona_conflict' | 'suspected_secret_leak' | 'suspected_cross_ip_contamination';
+export interface WorldModelAssistedFinding {
+    code: WorldModelAssistedFindingCode;
+    layer: 'model_assisted';
+    /** `potential` until a person decides. Confirming records an opinion against
+     *  the finding; it changes nothing about the story, canon, ledger or state. */
+    status: 'potential' | 'confirmed' | 'dismissed';
+    severity: 'warning' | 'info';
+    /** Stable across scans for the same judgement, so a dismissal sticks. */
+    findingId: string;
+    /** Assembled server-side from committed rows. The model picks which rows;
+     *  it never writes evidence. */
+    evidence: Array<{
+        turnId?: string;
+        roleId?: string;
+    }>;
+    /** The model's own words, bounded, and typed apart from evidence. */
+    suggestion?: {
+        kind: 'author_note';
+        text: string;
+    };
+    reviewedBy?: string;
+    reviewedAt?: string;
+}
+/** Why the model layer produced less than a full pass, when it was asked for. */
+export type WorldModelLayerNote = 'disabled_server' | 'not_declared' | 'rate_limited' | 'unavailable' | 'incomplete';
+export type WorldConsistencyReport = {
+    status: 'complete' | 'incomplete';
+    contractVersion: number;
+    findings: WorldConsistencyFinding[];
+    coverage: WorldConsistencyCoverage[];
+    entriesScanned: number;
+    findingsTruncated: boolean;
+    /** Present only when `status` is `incomplete`. Pass it back to continue. */
+    cursor?: number;
+    /** Present ONLY when you asked for `model_assisted`. A default call
+     *  carries neither this key nor `modelAssistedNote`. */
+    modelAssistedFindings?: WorldModelAssistedFinding[];
+    modelAssistedNote?: WorldModelLayerNote;
+} | {
+    status: 'rate_limited';
+    retryAfterSec: number;
+} | {
+    status: 'unavailable';
+    reason: 'world_unavailable';
+};
 export declare class PouchyWorldClient {
     readonly projectId: string;
     private readonly baseUrl;
@@ -692,6 +882,29 @@ export declare class PouchyWorldClient {
         environmentRevision: number;
         state: Record<string, unknown>;
     }>;
+    /** What this world's own record proves about itself. World API 1.19.
+     *
+     *  A read-only scan: it commits nothing, asks no model, and repairs nothing.
+     *  Findings are deterministic — each one is two recorded things that cannot
+     *  both be true — so they are safe to act on without a human re-reading the
+     *  story, which is exactly what the model-assisted layer is not.
+     *
+     *  Check `status` first. `incomplete` means the walk was capped or the
+     *  datastore stopped answering: pass `cursor` back to continue, and do NOT
+     *  read an empty `findings` on that arm as a clean bill of health.
+     *
+     *  READ `coverage` BEFORE TRUSTING AN EMPTY `findings`. Some checks depend
+     *  on fields that older ledger rows do not carry, and those entries are
+     *  counted there rather than skipped in silence. A clean report that could
+     *  not examine half the history is not the same as a clean world.
+     *
+     *  Rate limited on two axes, project and IP. `status: 'rate_limited'`
+     *  arrives with HTTP 429 and `retryAfterSec`.
+     */
+    scanConsistency(environmentId: string, worldInstanceId: string, opts?: {
+        cursor?: number;
+        layers?: Array<'deterministic' | 'model_assisted'>;
+    }): Promise<WorldConsistencyReport>;
     /** Where the story is, and whether it can go on. World API 1.18.
      *
      *  A DERIVED checkpoint: nothing is stored to answer it, no model is asked,
@@ -786,16 +999,29 @@ export declare class PouchyWorldClient {
      *  (Batch 7). Idempotent on content — the same approved review exports to
      *  the same id forever, so replaying one is a no-op rather than a second
      *  script. `notify` also sends `world.script_approved` to the project's
-     *  webhooks, carrying lineage and identifiers but never the script body. */
+     *  webhooks, carrying lineage, identifiers and `contractVersion` but never
+     *  the script body.
+     *
+     *  `version` DEFAULTS TO 1 and omitting it sends no `version` at all, so a
+     *  caller written before V2 existed keeps receiving byte-identical exports.
+     *  Pass `version: 2` for the production contract (synopsis, character notes,
+     *  episodes, key moments, relation changes, divergence). Any other value is
+     *  refused by the server rather than coerced. */
     createApprovedExport(environmentId: string, worldInstanceId: string, draftId: string, editorialId: string, options?: {
         notify?: boolean;
+        version?: 1 | 2;
     }): Promise<ApprovedScriptExportRow>;
     listApprovedExports(environmentId: string, worldInstanceId: string, draftId: string, editorialId: string): Promise<{
         exports: unknown[];
     }>;
     /** The next Story Package as a CANDIDATE — validated, and returned rather
      *  than published. Publishing it is a separate act by a person, through
-     *  `createStoryPackage`. Only evidence-origin material becomes canon. */
+     *  `createStoryPackage`. Only evidence-origin material becomes canon.
+     *
+     *  VERSION 1 EXPORTS ONLY. A version 2 export is refused with 422: this is
+     *  the one path from an export into published canon, and which V2 fields may
+     *  become canon has not been decided. Export the approval as version 1 and
+     *  derive from that. */
     deriveStoryPackageCandidate(environmentId: string, worldInstanceId: string, draftId: string, editorialId: string, exportId: string, options?: {
         name?: string;
         summary?: string;

package/dist/index.js

@@ -23,7 +23,7 @@ import { createHash, createHmac, randomUUID } from 'node:crypto';
  *  a project is running — which is exactly the field you reach for when a
  *  customer's integration behaves like an older SDK than they say they have.
  *  It sat at '0.1.0' for eight releases before anything compared the two. */
-export const WORLD_SDK_VERSION = '0.15.0';
+export const WORLD_SDK_VERSION = '0.18.0';
 export const DEFAULT_BASE_URL = 'https://pouchy.ai/v1';
 /** Read the commit turn id out of an envelope, so the signature covers the id
  *  the server will commit under. The payload half is base64url JSON; the
@@ -297,6 +297,40 @@ export class PouchyWorldClient {
     getWorldState(environmentId, worldInstanceId) {
         return this.read(`/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/state`, `/admin/environments/${environmentId}/instances/${worldInstanceId}/state`);
     }
+    /** What this world's own record proves about itself. World API 1.19.
+     *
+     *  A read-only scan: it commits nothing, asks no model, and repairs nothing.
+     *  Findings are deterministic — each one is two recorded things that cannot
+     *  both be true — so they are safe to act on without a human re-reading the
+     *  story, which is exactly what the model-assisted layer is not.
+     *
+     *  Check `status` first. `incomplete` means the walk was capped or the
+     *  datastore stopped answering: pass `cursor` back to continue, and do NOT
+     *  read an empty `findings` on that arm as a clean bill of health.
+     *
+     *  READ `coverage` BEFORE TRUSTING AN EMPTY `findings`. Some checks depend
+     *  on fields that older ledger rows do not carry, and those entries are
+     *  counted there rather than skipped in silence. A clean report that could
+     *  not examine half the history is not the same as a clean world.
+     *
+     *  Rate limited on two axes, project and IP. `status: 'rate_limited'`
+     *  arrives with HTTP 429 and `retryAfterSec`.
+     */
+    scanConsistency(environmentId, worldInstanceId, opts = {}) {
+        // The query rides the third argument, not the path template. Both are
+        // sent identically; keeping the path a pure template is what lets the
+        // admin-lane gate check that every `/admin/...` the SDK sends is a route
+        // that actually exists.
+        const q = new URLSearchParams();
+        if (opts.cursor !== undefined)
+            q.set('cursor', String(opts.cursor));
+        // Omitted means deterministic only, with zero model calls — the default
+        // stays what it was, so upgrading the SDK changes no behaviour.
+        if (opts.layers?.length)
+            q.set('layers', opts.layers.join(','));
+        const suffix = q.toString() ? `?${q}` : '';
+        return this.read(`/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/consistency`, `/admin/environments/${environmentId}/instances/${worldInstanceId}/consistency`, suffix);
+    }
     /** Where the story is, and whether it can go on. World API 1.18.
      *
      *  A DERIVED checkpoint: nothing is stored to answer it, no model is asked,
@@ -424,16 +458,31 @@ export class PouchyWorldClient {
      *  (Batch 7). Idempotent on content — the same approved review exports to
      *  the same id forever, so replaying one is a no-op rather than a second
      *  script. `notify` also sends `world.script_approved` to the project's
-     *  webhooks, carrying lineage and identifiers but never the script body. */
+     *  webhooks, carrying lineage, identifiers and `contractVersion` but never
+     *  the script body.
+     *
+     *  `version` DEFAULTS TO 1 and omitting it sends no `version` at all, so a
+     *  caller written before V2 existed keeps receiving byte-identical exports.
+     *  Pass `version: 2` for the production contract (synopsis, character notes,
+     *  episodes, key moments, relation changes, divergence). Any other value is
+     *  refused by the server rather than coerced. */
     createApprovedExport(environmentId, worldInstanceId, draftId, editorialId, options = {}) {
-        return this.owner('POST', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/editorial/${editorialId}/approved-export`, options.notify ? { notify: true } : {});
+        return this.owner('POST', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/editorial/${editorialId}/approved-export`, {
+            ...(options.notify ? { notify: true } : {}),
+            ...(options.version === undefined ? {} : { version: options.version })
+        });
     }
     listApprovedExports(environmentId, worldInstanceId, draftId, editorialId) {
         return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/editorial/${editorialId}/approved-export`);
     }
     /** The next Story Package as a CANDIDATE — validated, and returned rather
      *  than published. Publishing it is a separate act by a person, through
-     *  `createStoryPackage`. Only evidence-origin material becomes canon. */
+     *  `createStoryPackage`. Only evidence-origin material becomes canon.
+     *
+     *  VERSION 1 EXPORTS ONLY. A version 2 export is refused with 422: this is
+     *  the one path from an export into published canon, and which V2 fields may
+     *  become canon has not been decided. Export the approval as version 1 and
+     *  derive from that. */
     deriveStoryPackageCandidate(environmentId, worldInstanceId, draftId, editorialId, exportId, options = {}) {
         return this.owner('POST', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/editorial/${editorialId}/approved-export/candidate?exportId=${encodeURIComponent(exportId)}`, options);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pouchy_ai/world-sdk",
-	"version": "0.15.0",
+	"version": "0.18.0",
 	"description": "Server-side TypeScript client for Pouchy World \u2014 story packages, world definitions, world sessions, coordinated turns, trusted events, replay verification and script drafts. Node only: it holds a project Secret Key and a source signing key, which never belong in a browser or a mobile app.",
 	"type": "module",
 	"license": "SEE LICENSE IN LICENSE",