@pouchy_ai/world-sdk 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @pouchy_ai/world-sdk
 
+## 0.24.0
+
+- **`startNextEpisode` now rides the MACHINE lane** (Secret Key + provider
+  signature, id namespace `epn:`) — the same two proofs as `runTurn` — so an
+  unattended serial backend can advance its own player's worldline. Before
+  this it required the expiring owner token, which made serial UX impossible
+  for an integrator: the backend that drives every beat of the story could
+  not move it to the next episode (#2998).
+- The method signature is unchanged (`startNextEpisode(environmentId,
+  worldInstanceId)`); an optional `{ requestId }` third argument pins the
+  signature id slot for callers that want to supply their own.
+- The server still accepts the owner lane, and still exposes no `/admin`
+  mirror — an admin key proves the project, never the Provider.
+- Idempotence is untouched: the run id stays server-derived from the
+  worldline, the episode and the revision it starts at; `requestId` is a
+  signature slot, not an idempotency key.
+- Server-side this is world API 1.30.0.
+
 ## 0.23.0
 
 - **`runTurn` gains `focusRoles?: string[]`** — narrow one beat to the named

package/README.md

@@ -45,7 +45,10 @@ const world = new PouchyWorldClient({
 **Authoring** — `createStoryPackage`, `publishStoryPackage`, `getStoryPackage`,
 `listStoryPackages`, `createWorld`, `publishWorld`, `getWorld`, `listWorlds`.
 
-**Running** — `createWorldSession`, `runTurn`, `sendEvent`.
+**Running** — `createWorldSession`, `runTurn`, `sendEvent`,
+`startNextEpisode` (machine lane since 0.24.0 — an unattended serial backend
+can advance its own player's worldline to the next episode and receive the
+carryover).
 
 **Deliberating** — `deliberate`, `selectCandidate`. Ask for a couple of public
 directions a beat could take, then commit the one the player picked. Off unless

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.23.0";
+export declare const WORLD_SDK_VERSION = "0.24.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. */
@@ -1032,10 +1032,17 @@ export declare class PouchyWorldClient {
      *  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>;
+     *  MACHINE LANE since 0.24.0 (#2998, world API 1.30.0): a Secret Key plus a
+     *  provider signature in the `epn:` namespace — the same two proofs as
+     *  `runTurn`, because the party trusted to author every beat, including the
+     *  one that ends an episode, is the party deciding the story moves on. So
+     *  an unattended serial backend can now advance its own player's worldline.
+     *  (Before 0.24.0 this rode the owner token; the server still accepts that
+     *  lane, and still exposes no `/admin` mirror — an admin key proves the
+     *  project, never the Provider.) */
+    startNextEpisode(environmentId: string, worldInstanceId: string, opts?: {
+        requestId?: 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.23.0';
+export const WORLD_SDK_VERSION = '0.24.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
@@ -356,11 +356,20 @@ export class PouchyWorldClient {
      *  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`, {});
+     *  MACHINE LANE since 0.24.0 (#2998, world API 1.30.0): a Secret Key plus a
+     *  provider signature in the `epn:` namespace — the same two proofs as
+     *  `runTurn`, because the party trusted to author every beat, including the
+     *  one that ends an episode, is the party deciding the story moves on. So
+     *  an unattended serial backend can now advance its own player's worldline.
+     *  (Before 0.24.0 this rode the owner token; the server still accepts that
+     *  lane, and still exposes no `/admin` mirror — an admin key proves the
+     *  project, never the Provider.) */
+    startNextEpisode(environmentId, worldInstanceId, opts = {}) {
+        const requestId = opts.requestId ?? newTurnId('epn-req');
+        return this.signed(`/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/episodes/next`, { requestId }, 
+        // Namespaced id slot: an episode-start signature can never be
+        // replayed onto the turn door, the events ingress or a deliberation.
+        `epn:${requestId}`);
     }
     /** Publish the next world revision. Existing world INSTANCES keep the
      *  revision they were created on — a published change reaches new instances

package/package.json

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