@pouchy_ai/world-sdk 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @pouchy_ai/world-sdk
 
+## 0.22.0
+
+- **`startNextEpisode(environmentId, worldInstanceId)`** — start the next
+  episode of a worldline that just finished one, and receive the CARRYOVER.
+- The worldline does **not** restart. Its `worldInstanceId`, membership, state
+  and ledger all continue; the episode moves on. Nothing is copied and nothing
+  is deleted, so there is no migration to get wrong.
+- **Idempotent.** The run id is derived from the worldline, the episode and the
+  revision it starts at, so a retry lands on the same run and answers
+  `created: false` rather than forking the story.
+- **Owner token only** — no `/admin` mirror, same reasoning as `preflightWorld`:
+  the mirror carries reads, and this is the write that decides a story moves on.
+- New types: `WorldCarryoverV1`, `WorldNextEpisodeResponse`. The carryover is a
+  **projection** of facts the worldline already holds — canon it established,
+  where the characters stand, threads left hanging, setups never paid off.
+  Role-private notes are never in it, and no memory is carried because the world
+  runtime writes none.
+- Server-side this is world API 1.28.0.
+
+## 0.21.0
+
+- **`WorldProgressCheckpointV1.episode`** — which episode a serial worldline is
+  playing, its beats-spent and turn budget, and the ending once it has one.
+  Absent for every world whose pinned story is not a serial, which is most of
+  them, so nothing an existing integration reads has changed shape.
+- **Type-only.** No new method, no new route: `getProgress` already returned
+  this checkpoint and now returns one more optional field.
+- `beatsCommitted` and `turnBudget` are two numbers, **not a ratio** — the same
+  rule as `completedNodeCount` / `declaredNodeCount`. A budget is the ceiling at
+  which the author's fallback ending fires, not a denominator of progress.
+- `endingId` is decided **server-side** from committed state and the package's
+  declared rules. No client, prompt or model supplies it.
+- Server-side this is world API 1.26.0 — Story Contract v3 (`series`). Publishing
+  a v3 package needs `POUCHY_STORY_CONTRACT_V3_WRITE` on the deployment; until
+  then such a publish is refused with `code: "story_contract_v3_write_disabled"`.
+
 ## 0.20.0
 
 - **Seven methods for routes that already existed.** `getWorldOverview`,

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.20.0";
+export declare const WORLD_SDK_VERSION = "0.22.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. */
@@ -216,8 +216,81 @@ export interface WorldProgressCheckpointV1 {
         branchId: string;
         condition: string;
     }>;
+    /** The episode this worldline is playing, when its pinned story is a
+     *  serial. ABSENT for every non-serial world, which is most of them.
+     *
+     *  `beatsCommitted` and `turnBudget` are two numbers, not a ratio — same
+     *  rule as `completedNodeCount` / `declaredNodeCount`. A budget is the
+     *  ceiling at which the author's fallback ending fires, not a denominator
+     *  of progress.
+     *
+     *  `endingId` appears only once the episode is over. It is decided
+     *  server-side from committed state and the package's declared rules; no
+     *  client, prompt or model supplies it. */
+    episode?: {
+        seriesId: string;
+        episodeId: string;
+        title: string;
+        status: 'active' | 'ended';
+        beatsCommitted: number;
+        turnBudget: number;
+        endingId?: string;
+        endingTitle?: string;
+    };
     rebuildable: true;
 }
+/** What the next episode gets to stand on. A PROJECTION of facts the worldline
+ *  already holds, not a copy of them — nothing is moved and nothing is deleted.
+ *
+ *  Role-private notes are never here. Neither is memory: the world runtime
+ *  writes none, so there is nothing to inherit. */
+export interface WorldCarryoverV1 {
+    contractVersion: 1;
+    fromEpisodeId: string;
+    fromEndingId: string;
+    toEpisodeId: string;
+    /** Canon the previous episode established — ids AND the author's text. */
+    canonFacts: Array<{
+        factId: string;
+        text: string;
+    }>;
+    canonFactsTruncated: boolean;
+    /** Where the characters stand. Public by definition. */
+    relations: Array<{
+        between: [string, string];
+        descriptor: string;
+    }>;
+    relationsTruncated: boolean;
+    /** Declared nodes the previous episode never completed. */
+    unresolvedThreads: Array<{
+        nodeId: string;
+        objective: string;
+    }>;
+    unresolvedThreadsTruncated: boolean;
+    /** Declared facts never revealed — setups it did not pay off. Not called
+     *  "promises": a promise is something a character made, which this system
+     *  does not model. */
+    unfulfilledSetups: Array<{
+        factId: string;
+        text: string;
+    }>;
+    unfulfilledSetupsTruncated: boolean;
+}
+export interface WorldNextEpisodeResponse {
+    /** False on a retry that landed on the run already started. */
+    created: boolean;
+    episode: {
+        seriesId: string;
+        episodeId: string;
+        episodeRunId: string;
+        status: 'active' | 'ended';
+        startedAt: string;
+        startedAtRevision: number;
+        startedFromEpisodeId?: string;
+        startedFromEndingId?: string;
+    };
+    carryover: WorldCarryoverV1;
+}
 export interface WorldTurnReadback {
     turnId: string;
     worldInstanceId: string;
@@ -949,6 +1022,20 @@ export declare class PouchyWorldClient {
      *  around: `getWorldOverview` carries `ready` and `blockers` and IS
      *  mirrored, so a machine has the readiness answer it needs. */
     preflightWorld(environmentId: string): Promise<unknown>;
+    /** Start the NEXT episode of a worldline that just finished one.
+     *
+     *  The worldline does NOT restart. Its `worldInstanceId`, membership, state
+     *  and ledger all continue — that is the point — and this moves the episode
+     *  on and hands back the CARRYOVER: what the next episode gets to stand on.
+     *
+     *  Idempotent. The run id is derived from the worldline, the episode and the
+     *  revision it starts at, so a retried call lands on the same run and
+     *  answers `created: false` rather than forking the story.
+     *
+     *  OWNER TOKEN ONLY — no `/admin` mirror, on the same reasoning as
+     *  `preflightWorld`: the mirror carries reads, and this is the write that
+     *  decides a story moves on. */
+    startNextEpisode(environmentId: string, worldInstanceId: string): Promise<WorldNextEpisodeResponse>;
     /** Publish the next world revision. Existing world INSTANCES keep the
      *  revision they were created on — a published change reaches new instances
      *  only, which is what keeps a running story from changing runtime or rules

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.20.0';
+export const WORLD_SDK_VERSION = '0.22.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
@@ -346,6 +346,22 @@ export class PouchyWorldClient {
     preflightWorld(environmentId) {
         return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}/preflight`);
     }
+    /** Start the NEXT episode of a worldline that just finished one.
+     *
+     *  The worldline does NOT restart. Its `worldInstanceId`, membership, state
+     *  and ledger all continue — that is the point — and this moves the episode
+     *  on and hands back the CARRYOVER: what the next episode gets to stand on.
+     *
+     *  Idempotent. The run id is derived from the worldline, the episode and the
+     *  revision it starts at, so a retried call lands on the same run and
+     *  answers `created: false` rather than forking the story.
+     *
+     *  OWNER TOKEN ONLY — no `/admin` mirror, on the same reasoning as
+     *  `preflightWorld`: the mirror carries reads, and this is the write that
+     *  decides a story moves on. */
+    startNextEpisode(environmentId, worldInstanceId) {
+        return this.owner('POST', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/episodes/next`, {});
+    }
     /** Publish the next world revision. Existing world INSTANCES keep the
      *  revision they were created on — a published change reaches new instances
      *  only, which is what keeps a running story from changing runtime or rules

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pouchy_ai/world-sdk",
-	"version": "0.20.0",
+	"version": "0.22.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",