@pouchy_ai/world-sdk 0.24.0 → 0.25.0

package/CHANGELOG.md

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

package/README.md

@@ -240,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.24.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

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.24.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];
@@ -870,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.24.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",