@pouchy_ai/world-sdk 0.30.0 → 0.31.0

package/CHANGELOG.md

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

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.30.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.
@@ -1166,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.30.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

package/package.json

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