@pouchy_ai/world-sdk 0.20.0 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # @pouchy_ai/world-sdk
 
+## 0.23.0
+
+- **`runTurn` gains `focusRoles?: string[]`** — narrow one beat to the named
+  roles: an interview, a one-on-one scene, a whispered aside. Before this,
+  every caller beat ran (and billed) every bound role up to the server cap,
+  and a one-on-one scene was impossible to express through the API.
+- **Shrink-only.** The server intersects the focus with the bound story cast,
+  mirroring the event lane's subscription routing: it can never widen a beat
+  past the roles the story declares or past the server's own cap. A focus
+  that matches no bound role is refused as `no selectable role` and spends
+  nothing.
+- Roles outside the focus are **not run and not billed**; the result's
+  `skippedRoles` records each as `'not focused'` — a new member of the skip
+  vocabulary — so the readback stays honest about who was passed over.
+- Absent or empty means every bound role answers, exactly as before. No
+  existing call changes behaviour.
+- Server-side this is world API 1.29.0.
+
+## 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/README.md

@@ -115,6 +115,23 @@ await world.runTurn({
 no single commit for a deterministic write to ride, and sending patches to one
 answers 422 rather than dropping them quietly.
 
+**Focusing a beat on some of the cast.** By default every bound role answers a
+beat (up to the server cap). For an interview or a one-on-one scene, pass
+`focusRoles` and only those roles run — the rest are not billed and are
+recorded in `skippedRoles` as `'not focused'`:
+
+```ts
+const beat = await world.runTurn({
+  environmentId, worldInstanceId,
+  text: 'Amara, what did you see?',
+  focusRoles: ['amara']
+});
+```
+
+Shrink-only: the server intersects the focus with the bound story cast, so it
+can never widen a beat, and a focus matching no bound role is refused as
+`no selectable role` without spending anything.
+
 **Resuming after a crash.** `getTurn` returns the same fields the live result
 did — `nextOptions` included — so a recovered session can offer the audience
 the choices it was about to. To catch up on beats you missed entirely, store

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.23.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
@@ -1233,6 +1320,15 @@ export declare class PouchyWorldClient {
         turnId?: string;
         text: string;
         sourceRoleId?: string;
+        /** Narrow this beat to the named roles — an interview, a one-on-one
+         *  scene, a whispered aside. Shrink-only: the server intersects it with
+         *  the bound story cast, so it can never widen the beat past the roles
+         *  the story declares or the server's own cap. Roles outside the focus
+         *  are not run and not billed; they appear in the result's
+         *  `skippedRoles` as `'not focused'`. A focus that matches no bound
+         *  role is refused as "no selectable role" and spends nothing. Absent
+         *  or empty means every bound role answers, exactly as before. */
+        focusRoles?: readonly string[];
         traceId?: string;
         /** PROVIDER-authored state changes, committed with this beat.
          *

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.23.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
@@ -684,6 +700,7 @@ export class PouchyWorldClient {
                 kind: 'user',
                 text: input.text,
                 ...(input.sourceRoleId ? { sourceRoleId: input.sourceRoleId } : {}),
+                ...(input.focusRoles?.length ? { focusRoles: [...input.focusRoles] } : {}),
                 ...(input.proposedPatches ? { proposedPatches: input.proposedPatches } : {})
             },
             ...(input.traceId ? { traceId: input.traceId } : {})

package/package.json

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