@pouchy_ai/world-sdk 0.28.0 → 0.29.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @pouchy_ai/world-sdk
 
+## 0.29.0
+
+- **`skippedRoles[].code`** — the machine half of "why this role did not
+  speak", as a closed `WorldSkipCode` union, plus `skipSpentNoModelCall(code)`
+  for the one derived question every consumer asks of it.
+
+  `reason` has always been a human sentence and stays one; nothing should key
+  off it. This exists because an integrator, given the reason prefixes in a
+  letter (the spec published none), built a cost model on
+  `reason.startsWith('turn error:')`. Their own words for the exposure: rename
+  that prefix and "we would not error — we would quietly file that class as
+  costing nothing." The same argument the rejection taxonomy made for
+  `rejectedEffects[].code`, applied to the sibling array that missed it.
+
+  Twelve codes. Eight of them mean no model call was made — `not_focused`,
+  `role_cap_reached`, `no_actor_bound`, `deadline_exhausted`, `not_admitted`,
+  `actor_unavailable`, `session_busy`, `content_policy`. Two mean a model ran or
+  may have: `turn_error` (deliberately does NOT promise a call happened —
+  context assembly failing and a provider dying mid-stream both land there) and
+  `no_message`. Two are beats where the role DID speak and the line was
+  withheld: `effect_refused`, `conflict_undelivered`.
+
+  Additive and optional: absent from a server predating the taxonomy, which
+  reads as unknown, never as a value. `skipSpentNoModelCall` returns false for
+  an unknown code and for `turn_error`, on the principle that a cost model
+  which under-counts silently is worse than one that over-counts visibly.
+
+## 0.28.1
+
+- **`WorldApiError.errorId`** — the server's lookup reference (`err_…`) for a
+  persisted 5xx, when the envelope carried one. An uncaught world-plane fault is
+  sanitized to "An unexpected error occurred." before it leaves the server; the
+  `errorId` on that envelope is the one thing an operator can resolve to the
+  real cause, and the client read `error` / `code` / `retryAfterSec` and dropped
+  it — so a 5xx gave you `500 server_error` and nothing to quote. Additive;
+  absent on every 4xx and on a 5xx that was not persisted; string-only, like
+  `serverCode`. Quote it in a support request.
+
 ## 0.28.0
 
 - **`WorldApiError.serverCode`** — the server's own machine-readable `code`

package/README.md

@@ -121,7 +121,7 @@ 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'`:
+recorded in `skippedRoles` with `code: 'not_focused'`:
 
 ```ts
 const beat = await world.runTurn({
@@ -135,6 +135,31 @@ 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.
 
+**Why a role was passed over.** Each `skippedRoles` entry carries a `reason`
+(the human line, which carries the sub-cause and is free to be reworded) and a
+`code` — a closed `WorldSkipCode`. **Key off the code, never the reason.**
+Reading an error string to decide what happened is how a message edit silently
+reclassifies a whole class; this SDK ships the enum precisely so you do not
+have to pattern-match prose.
+
+```ts
+import { skipSpentNoModelCall } from '@pouchy_ai/world-sdk';
+
+for (const s of beat.skippedRoles) {
+  if (s.code === undefined) audit.unknown(s.roleId, s.reason);   // old server
+  else if (skipSpentNoModelCall(s.code)) cost.free(s.roleId, s.code);
+  else cost.mayHaveSpent(s.roleId, s.code);
+}
+```
+
+`skipSpentNoModelCall` answers false for `turn_error` even though it often is
+free: context assembly failing and a provider dying mid-stream both land there
+and cannot be told apart afterwards, so a cost model that counted it free would
+under-count silently. It answers false for an unknown code for the same reason.
+
+To read a beat, subtract: a role in `selectedRoles` and absent from
+`skippedRoles` chose silence; a role listed here never ran.
+
 **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
@@ -251,7 +276,8 @@ an `approved` editorial can be exported.
 `newTurnId` / `isReservedTurnId` (idempotency), `describeTurn` (read a result
 without guessing), `WorldApiError` with typed codes, `.retryable`,
 `serverCode` (the server's own `code` on a refusal — which 409, since `code`
-maps the status), and `rejectedEffects` (which of YOUR proposed ops the world
+maps the status), `errorId` (the server's `err_…` lookup reference on a
+persisted 5xx — quote it in a support request), 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.28.0";
+export declare const WORLD_SDK_VERSION = "0.29.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. */
@@ -61,6 +61,13 @@ export declare class WorldApiError extends Error {
      *  dropped `code` on the floor, so the one carrier an integrator could
      *  branch on never arrived. */
     readonly serverCode?: string;
+    /** The server's lookup reference for a persisted 5xx (`err_…`), when the
+     *  envelope carried one. A world-plane fault is sanitized to "An unexpected
+     *  error occurred." before it leaves the server; the `errorId` is the ONE
+     *  greppable thing the operator can resolve to the real cause — quote it in
+     *  a support request. Absent on every 4xx and on a 5xx that was not
+     *  persisted (0.28.1; until then the client dropped it). */
+    readonly errorId?: string;
     readonly retryAfterSec?: number;
     /** Why the world refused the effects you proposed — per op, with the
      *  server's own reason and code.
@@ -90,6 +97,7 @@ export declare class WorldApiError extends Error {
         message: string;
         detail?: string;
         serverCode?: string;
+        errorId?: string;
         retryAfterSec?: number;
         rejectedEffects?: readonly {
             readonly index: number;
@@ -168,6 +176,7 @@ export interface WorldTurnResult {
     skippedRoles: Array<{
         roleId: string;
         reason: string;
+        code?: WorldSkipCode;
     }>;
     nextOptions: Array<{
         branchId: string;
@@ -373,6 +382,7 @@ export interface WorldTurnReadback {
     skippedRoles?: Array<{
         roleId: string;
         reason: string;
+        code?: WorldSkipCode;
     }>;
     repairs?: Array<{
         roleId: string;
@@ -517,6 +527,29 @@ export interface EditorialDraftRow {
  *  content problem. */
 /** The shared refusal taxonomy (Batch 7). Only `narrative_conflict` is content. */
 export type WorldRejectionCode = 'narrative_conflict' | 'policy_rejection' | 'schema_rejection' | 'canon_rejection' | 'concurrency_rejection' | 'repair_failure';
+/** WHY a role that was in the cast did not speak — the machine half of
+ *  `skippedRoles[].reason`, added 2026-09-09.
+ *
+ *  `reason` remains the human line and carries the sub-cause (which admission
+ *  rule, which runtime error); it is free to be reworded, so do not key off it.
+ *  This exists because an integrator built a cost model on
+ *  `reason.startsWith('turn error:')` — a rename on the platform side would not
+ *  have errored, it would have silently reclassified that whole class.
+ *
+ *  No model call was made for the first eight; a model ran, or may have, for
+ *  `turn_error` and `no_message`; the last two are beats where the role DID
+ *  speak and the line was withheld. `skipSpentNoModelCall` below is that split,
+ *  so a consumer does not re-derive it. Absent on turns from a server predating
+ *  the taxonomy — read that as unknown, never as a value. */
+export type WorldSkipCode = 'not_focused' | 'role_cap_reached' | 'no_actor_bound' | 'deadline_exhausted' | 'not_admitted' | 'actor_unavailable' | 'session_busy' | 'content_policy' | 'turn_error' | 'no_message' | 'effect_refused' | 'conflict_undelivered';
+/** Did this skip happen before any model call — is the role's silence free?
+ *
+ *  `turn_error` is deliberately NOT in the free set even though it often is:
+ *  context assembly failing and a provider dying mid-stream both land there and
+ *  cannot be told apart after the fact, so a cost model that counted it free
+ *  would under-count silently. Returns false for an unknown code, for the same
+ *  reason. */
+export declare function skipSpentNoModelCall(code: WorldSkipCode | undefined): boolean;
 /** True for every code except `narrative_conflict`. */
 export declare function isDefectRejection(code: WorldRejectionCode | undefined): boolean;
 export interface WorldInstanceMetrics {

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.28.0';
+export const WORLD_SDK_VERSION = '0.29.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
@@ -71,6 +71,13 @@ export class WorldApiError extends Error {
      *  dropped `code` on the floor, so the one carrier an integrator could
      *  branch on never arrived. */
     serverCode;
+    /** The server's lookup reference for a persisted 5xx (`err_…`), when the
+     *  envelope carried one. A world-plane fault is sanitized to "An unexpected
+     *  error occurred." before it leaves the server; the `errorId` is the ONE
+     *  greppable thing the operator can resolve to the real cause — quote it in
+     *  a support request. Absent on every 4xx and on a 5xx that was not
+     *  persisted (0.28.1; until then the client dropped it). */
+    errorId;
     retryAfterSec;
     /** Why the world refused the effects you proposed — per op, with the
      *  server's own reason and code.
@@ -97,6 +104,8 @@ export class WorldApiError extends Error {
             this.detail = input.detail;
         if (input.serverCode !== undefined)
             this.serverCode = input.serverCode;
+        if (input.errorId !== undefined)
+            this.errorId = input.errorId;
         if (input.retryAfterSec !== undefined)
             this.retryAfterSec = input.retryAfterSec;
         if (input.rejectedEffects !== undefined)
@@ -297,6 +306,23 @@ export function describeTurn(result) {
             ` delivery ${result.deliveryStatus}`
     };
 }
+/** Did this skip happen before any model call — is the role's silence free?
+ *
+ *  `turn_error` is deliberately NOT in the free set even though it often is:
+ *  context assembly failing and a provider dying mid-stream both land there and
+ *  cannot be told apart after the fact, so a cost model that counted it free
+ *  would under-count silently. Returns false for an unknown code, for the same
+ *  reason. */
+export function skipSpentNoModelCall(code) {
+    return (code === 'not_focused' ||
+        code === 'role_cap_reached' ||
+        code === 'no_actor_bound' ||
+        code === 'deadline_exhausted' ||
+        code === 'not_admitted' ||
+        code === 'actor_unavailable' ||
+        code === 'session_busy' ||
+        code === 'content_policy');
+}
 /** True for every code except `narrative_conflict`. */
 export function isDefectRejection(code) {
     return code !== undefined && code !== 'narrative_conflict';
@@ -940,12 +966,18 @@ export class PouchyWorldClient {
             const serverCode = parsed && typeof parsed === 'object' && typeof parsed.code === 'string'
                 ? parsed.code
                 : undefined;
+            // Same string-only rule as `serverCode`: the envelope's lookup ref, or
+            // nothing — never a coerced non-string.
+            const errorId = parsed && typeof parsed === 'object' && typeof parsed.errorId === 'string'
+                ? parsed.errorId || undefined
+                : undefined;
             throw new WorldApiError({
                 code: codeForStatus(response.status),
                 status: response.status,
                 message: `${method} ${path} → ${response.status}`,
                 ...(detail !== undefined ? { detail } : {}),
                 ...(serverCode !== undefined ? { serverCode } : {}),
+                ...(errorId !== undefined ? { errorId } : {}),
                 ...(retryAfterSec !== undefined ? { retryAfterSec } : {}),
                 ...(rejectedEffects !== undefined ? { rejectedEffects } : {})
             });

package/package.json

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