@pouchy_ai/world-sdk 0.23.0 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @pouchy_ai/world-sdk
 
+## 0.25.0
+
+- **`WorldApiError.rejectedEffects`** — a rejected turn (422) now arrives with
+  the per-op reasons the server computed, instead of a bare status. The turns
+  door answers a refused effect batch with the FULL turn result rather than
+  `{ error }`, so `detail` was undefined for exactly the refusal that has the
+  most to say, and an integrator got `POST … → 422` and nothing else.
+- This is load-bearing rather than cosmetic because patch validation is
+  ALL-OR-NOTHING: one bad op voids the batch, the turn moves nothing, and
+  "which of my ops was it" is the only useful question. Measured cost of not
+  having it: two rounds of field testing spent guessing which of five ops was
+  bad while the server had already written the answer (`node "node.hear-amara"
+  requires "node.warning" to be completed first`).
+- Each entry carries `index`, `reason`, and optionally `code` / `roleId` /
+  `kind`. Read defensively from an untrusted body: entries without a string
+  `reason` are dropped, and the field is ABSENT (never `[]`) when the server
+  named nothing — "said nothing" and "refused nothing" stay distinguishable.
+- Purely additive; `code`, `status`, `detail`, `retryAfterSec` and `.retryable`
+  are unchanged, and knowing why a batch was refused does not make a 422
+  retryable.
+- See `docs/world-sdk-errors.md` → “`rejectedEffects`” for the two readings
+  that matter (an undeclared id means a stale pinned revision; an unmet
+  prerequisite means an earlier beat never committed).
+
+## 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
@@ -237,7 +240,9 @@ an `approved` editorial can be exported.
 
 **Helpers** — `signSourceRequest` (the exact canonical the server verifies),
 `newTurnId` / `isReservedTurnId` (idempotency), `describeTurn` (read a result
-without guessing), `WorldApiError` with typed codes and `.retryable`.
+without guessing), `WorldApiError` with typed codes, `.retryable`, and
+`rejectedEffects` (which of YOUR proposed ops the world refused, and why —
+validation is all-or-nothing, so one bad op moves nothing).
 
 ## When a signed door refuses you
 

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.25.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. */
@@ -41,12 +41,41 @@ export declare class WorldApiError extends Error {
     /** The server's own message, when it sent one. */
     readonly detail?: string;
     readonly retryAfterSec?: number;
+    /** Why the world refused the effects you proposed — per op, with the
+     *  server's own reason and code.
+     *
+     *  A rejected turn (422) does NOT answer with `{ error }` like every other
+     *  refusal: its body is the full turn result, and the reasons live in
+     *  `rejectedEffects`. So `detail` was undefined for exactly the refusal
+     *  that has the most to say, and an integrator got `POST … → 422` and
+     *  nothing else. Measured cost: two rounds of field testing spent guessing
+     *  which of five ops in a batch was the bad one, while the server had
+     *  computed the answer (`node "node.hear-amara" requires "node.warning" to
+     *  be completed first`) and thrown it away at this line.
+     *
+     *  Patch validation is ALL-OR-NOTHING, which is what makes this
+     *  load-bearing rather than nice-to-have: one bad op voids the batch, so
+     *  "which one" is the only question worth asking. */
+    readonly rejectedEffects?: readonly {
+        readonly index: number;
+        readonly reason: string;
+        readonly roleId?: string;
+        readonly kind?: string;
+        readonly code?: string;
+    }[];
     constructor(input: {
         code: WorldErrorCode;
         status: number;
         message: string;
         detail?: string;
         retryAfterSec?: number;
+        rejectedEffects?: readonly {
+            readonly index: number;
+            readonly reason: string;
+            readonly roleId?: string;
+            readonly kind?: string;
+            readonly code?: string;
+        }[];
     });
     /** Worth trying again with the SAME idempotency key. A 409 is not: it means
      *  the world disagreed with the request, and repeating it will disagree
@@ -1032,10 +1061,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.25.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
@@ -61,6 +61,22 @@ export class WorldApiError extends Error {
     /** The server's own message, when it sent one. */
     detail;
     retryAfterSec;
+    /** Why the world refused the effects you proposed — per op, with the
+     *  server's own reason and code.
+     *
+     *  A rejected turn (422) does NOT answer with `{ error }` like every other
+     *  refusal: its body is the full turn result, and the reasons live in
+     *  `rejectedEffects`. So `detail` was undefined for exactly the refusal
+     *  that has the most to say, and an integrator got `POST … → 422` and
+     *  nothing else. Measured cost: two rounds of field testing spent guessing
+     *  which of five ops in a batch was the bad one, while the server had
+     *  computed the answer (`node "node.hear-amara" requires "node.warning" to
+     *  be completed first`) and thrown it away at this line.
+     *
+     *  Patch validation is ALL-OR-NOTHING, which is what makes this
+     *  load-bearing rather than nice-to-have: one bad op voids the batch, so
+     *  "which one" is the only question worth asking. */
+    rejectedEffects;
     constructor(input) {
         super(input.message);
         this.name = 'WorldApiError';
@@ -70,6 +86,8 @@ export class WorldApiError extends Error {
             this.detail = input.detail;
         if (input.retryAfterSec !== undefined)
             this.retryAfterSec = input.retryAfterSec;
+        if (input.rejectedEffects !== undefined)
+            this.rejectedEffects = input.rejectedEffects;
     }
     /** Worth trying again with the SAME idempotency key. A 409 is not: it means
      *  the world disagreed with the request, and repeating it will disagree
@@ -84,6 +102,38 @@ export class WorldApiError extends Error {
  *  delta-seconds number, then the HTTP-date form proxies and CDNs emit.
  *  Anything that is not a non-negative finite number is `undefined` — no
  *  guessing. */
+/** The per-op refusal reasons a rejected turn carries, defensively read.
+ *
+ *  Shaped from an untrusted body, so every field is checked rather than cast:
+ *  a client that promises `rejectedEffects[].reason` is a string and hands the
+ *  caller `undefined` has moved the failure one frame later, into the
+ *  integrator's own logging. Entries that are not a plausible refusal are
+ *  dropped, and an empty result is `undefined` — absent, not `[]`, so "the
+ *  server said nothing" and "the server refused nothing" stay different
+ *  readings. */
+function rejectedEffectsFrom(body) {
+    if (!body || typeof body !== 'object')
+        return undefined;
+    const raw = body.rejectedEffects;
+    if (!Array.isArray(raw))
+        return undefined;
+    const out = [];
+    for (const e of raw.slice(0, 64)) {
+        if (!e || typeof e !== 'object')
+            continue;
+        const r = e;
+        if (typeof r.reason !== 'string' || !r.reason)
+            continue;
+        out.push({
+            index: typeof r.index === 'number' ? r.index : -1,
+            reason: r.reason.slice(0, 500),
+            ...(typeof r.roleId === 'string' ? { roleId: r.roleId } : {}),
+            ...(typeof r.kind === 'string' ? { kind: r.kind } : {}),
+            ...(typeof r.code === 'string' ? { code: r.code } : {})
+        });
+    }
+    return out.length ? out : undefined;
+}
 function retryAfterFrom(res, body) {
     for (const k of ['retryAfterSec', 'retryAfter']) {
         const v = body?.[k];
@@ -356,11 +406,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
@@ -861,12 +920,14 @@ export class PouchyWorldClient {
                 ? String(parsed.error)
                 : undefined;
             const retryAfterSec = retryAfterFrom(response, parsed && typeof parsed === 'object' ? parsed : null);
+            const rejectedEffects = rejectedEffectsFrom(parsed);
             throw new WorldApiError({
                 code: codeForStatus(response.status),
                 status: response.status,
                 message: `${method} ${path} → ${response.status}`,
                 ...(detail !== undefined ? { detail } : {}),
-                ...(retryAfterSec !== undefined ? { retryAfterSec } : {})
+                ...(retryAfterSec !== undefined ? { retryAfterSec } : {}),
+                ...(rejectedEffects !== undefined ? { rejectedEffects } : {})
             });
         }
         return parsed;

package/package.json

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