@pouchy_ai/world-sdk 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # @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

package/README.md

@@ -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.16.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;
@@ -684,6 +773,44 @@ export interface WorldConsistencyCoverage {
     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;
@@ -693,6 +820,10 @@ export type WorldConsistencyReport = {
     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;
@@ -772,6 +903,7 @@ export declare class PouchyWorldClient {
      */
     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.
      *
@@ -867,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.16.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
@@ -324,6 +324,10 @@ export class PouchyWorldClient {
         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);
     }
@@ -454,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.16.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",