@pouchy_ai/world-sdk 0.28.1 → 0.29.0

package/CHANGELOG.md

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

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

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.1";
+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. */
@@ -176,6 +176,7 @@ export interface WorldTurnResult {
     skippedRoles: Array<{
         roleId: string;
         reason: string;
+        code?: WorldSkipCode;
     }>;
     nextOptions: Array<{
         branchId: string;
@@ -381,6 +382,7 @@ export interface WorldTurnReadback {
     skippedRoles?: Array<{
         roleId: string;
         reason: string;
+        code?: WorldSkipCode;
     }>;
     repairs?: Array<{
         roleId: string;
@@ -525,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.1';
+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
@@ -306,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';

package/package.json

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