@pouchy_ai/world-sdk 0.29.0 → 0.31.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @pouchy_ai/world-sdk
 
+## 0.31.0
+
+- **`WorldStateView`** — `getWorldState().state` is typed, instead of
+  `Record<string, unknown>`. The same shape is published in the world OpenAPI
+  (it said `anyObj`), and a census derives the field list from the projection
+  itself so the document and the runtime cannot drift.
+
+  Asked by an integrator building highlight triggers who needed three things
+  from `state` and could not answer any of them from anything published. They
+  declined to guess the keys from one live call, on the grounds that a key
+  which is merely PRESENT is a feature that vanishes silently on some later
+  change — and the symptom would have been "highlights stopped firing", with no
+  error. The prose that was there had already drifted: it never mentioned
+  `completedNodes`, which is exactly the field they concluded did not exist.
+
+  Two answers that surprise people, both because `getProgress` beside it
+  filters differently:
+
+  - **`flags` is EVERY flag**, not only those an author marked `public: true`.
+    That filter belongs to the progress checkpoint, whose audience is a
+    player's client. This door is the operator's, so forwarding these bytes to
+    a reader — including the spoiler risk in a flag's NAME — is your decision.
+  - **`completedNodes` gives node IDS.** The checkpoint reports only
+    `completedNodeCount` and says outright it is not a denominator.
+
+  Also additive on the envelope: `environmentId` and `storyPackageRef` are
+  returned by the route and were named in neither plane's document.
+
+## 0.30.0
+
+- **`SKIP_COST_MODEL_VERSION` / `SKIP_COST_MODEL_DIGEST`** — the cost model's
+  identity as of this build, so you can detect that the server regrouped a code
+  instead of finding out from your ledger.
+
+  Asked directly after 0.29.0 shipped: does `skipSpentNoModelCall` track the
+  server, and would a regrouping be a major bump? The answers are **no** and
+  **we will not promise that**. A published package is a SNAPSHOT — regroup a
+  code server-side and a pinned client keeps the old answer forever, with no
+  error, no code change of yours and green tests. And a promise to bump is a
+  claim about human behaviour with no process behind it; the same shape this
+  project already declined to sign for the moderation defaults.
+
+  So the grouping is published as data instead. `GET /v1/world/openapi` carries
+  `x-pouchy-cost-model` (`version`, `digest`, `noModelCall`, `modelMayHaveRun`)
+  on the `skippedRoles[].code` schema. Compare it against these two constants
+  and alarm on a mismatch — a check that fires on the condition itself rather
+  than on our remembering to signal it.
+
+  The digest covers group MEMBERSHIP only: reordering the enum or rewording a
+  comment never moves it; a code changing group always does.
+
 ## 0.29.0
 
 - **`skippedRoles[].code`** — the machine half of "why this role did not

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.29.0";
+export declare const WORLD_SDK_VERSION = "0.31.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. */
@@ -526,6 +526,43 @@ export interface EditorialDraftRow {
  *  purpose: one word answering both is how a delivery outage reads as a
  *  content problem. */
 /** The shared refusal taxonomy (Batch 7). Only `narrative_conflict` is content. */
+/** The USER projection of world state — what `getWorldState` returns.
+ *
+ *  Typed from 0.31.0. Before that it was `Record<string, unknown>`, and an
+ *  integrator building highlight triggers could not answer three basic
+ *  questions from anything published — the spec said `anyObj` and its prose
+ *  summary had drifted, omitting `completedNodes` entirely. They declined to
+ *  guess the keys from one live call, on the grounds that a key which is merely
+ *  PRESENT is a feature that disappears silently later. They were right, and
+ *  this is the fix.
+ *
+ *  TWO THINGS THAT SURPRISE PEOPLE, both because the progress checkpoint beside
+ *  this filters differently:
+ *
+ *  - `flags` is EVERY flag, not only those an author marked `public: true`.
+ *    That filter belongs to `getProgress`, whose audience is a player's client.
+ *    This door is the operator's — if you forward these bytes to a reader, the
+ *    decision (and the spoiler risk in a flag's NAME) is yours.
+ *  - `completedNodes` gives the node IDS. The checkpoint reports only
+ *    `completedNodeCount`, and says outright that it is not a denominator.
+ *
+ *  The role-private layer is never here. */
+export interface WorldStateView {
+    stateRevision: number;
+    clock: number;
+    sceneId?: string;
+    location?: string;
+    flags: Record<string, boolean | number | string>;
+    completedNodes: string[];
+    factsVisible: string[];
+    relations: Record<string, string>;
+    entities: Record<string, string>;
+    lastEntries: Array<{
+        entryId: string;
+        kind: string;
+        at: number;
+    }>;
+}
 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.
@@ -542,6 +579,21 @@ export type WorldRejectionCode = 'narrative_conflict' | 'policy_rejection' | 'sc
  *  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';
+/** The cost model's version and digest AS OF THIS SDK BUILD.
+ *
+ *  `skipSpentNoModelCall` below is a SNAPSHOT — a published package cannot
+ *  track a server that regroups a code later, and nothing would error if it
+ *  did: your code would not change, your tests would stay green, and your
+ *  billing would drift. So compare these against `x-pouchy-cost-model` in
+ *  `GET /v1/world/openapi` (the same document you already read for the enum) and
+ *  alarm on a mismatch. That check is worth more than any promise about version
+ *  bumps, because it fires on the condition itself rather than on our
+ *  remembering to signal it.
+ *
+ *  The digest covers group MEMBERSHIP only: reordering the enum or rewording a
+ *  comment never moves it. */
+export declare const SKIP_COST_MODEL_VERSION = "1.0.0";
+export declare const SKIP_COST_MODEL_DIGEST = "4a8369322817e3fa";
 /** 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:
@@ -1151,7 +1203,7 @@ export declare class PouchyWorldClient {
     getWorldState(environmentId: string, worldInstanceId: string): Promise<{
         worldInstanceId: string;
         environmentRevision: number;
-        state: Record<string, unknown>;
+        state: WorldStateView;
     }>;
     /** What this world's own record proves about itself. World API 1.19.
      *

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.29.0';
+export const WORLD_SDK_VERSION = '0.31.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,21 @@ export function describeTurn(result) {
             ` delivery ${result.deliveryStatus}`
     };
 }
+/** The cost model's version and digest AS OF THIS SDK BUILD.
+ *
+ *  `skipSpentNoModelCall` below is a SNAPSHOT — a published package cannot
+ *  track a server that regroups a code later, and nothing would error if it
+ *  did: your code would not change, your tests would stay green, and your
+ *  billing would drift. So compare these against `x-pouchy-cost-model` in
+ *  `GET /v1/world/openapi` (the same document you already read for the enum) and
+ *  alarm on a mismatch. That check is worth more than any promise about version
+ *  bumps, because it fires on the condition itself rather than on our
+ *  remembering to signal it.
+ *
+ *  The digest covers group MEMBERSHIP only: reordering the enum or rewording a
+ *  comment never moves it. */
+export const SKIP_COST_MODEL_VERSION = '1.0.0';
+export const SKIP_COST_MODEL_DIGEST = '4a8369322817e3fa';
 /** 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:

package/package.json

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