@pouchy_ai/world-sdk 0.25.1 → 0.27.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @pouchy_ai/world-sdk
 
+## 0.27.0
+
+- **`WorldProgressCheckpointV1.publicFlags` / `publicFlagsTruncated`** — Story
+  Contract **v4**: a declared flag may carry `public: true`, and the progress
+  checkpoint then carries that flag's name and value (the declared initial when
+  it was never set, `null` when there is neither), sorted by key. ALWAYS
+  present — an empty array for a story that publishes nothing — so absent never
+  reads as unknown. Flags the author did not mark public stay out of the
+  checkpoint, as every flag did before: a flag's name can itself be a spoiler.
+  This is the read a client needs for a RUNTIME exit — a character who leaves
+  for good — instead of a static scene list (design #23).
+- `StoryFlagSpec.public?: true` on the Story Package type. Declaring any public
+  flag makes a package contract v4; the server decides the version, and an
+  environment that has not enabled v4 writes answers 409
+  `story_contract_v4_write_disabled` with the field intact.
+
+## 0.26.0
+
+- **`WorldDeliberationResponse.viewTrimmed`** — whether the role's view had to
+  be trimmed to fit the previewer's input budget. The budget grows with the
+  worldline, so a long session reaches it where a short one never does, and a
+  previewer working from a cut-down view is not the same instrument as one that
+  saw the whole state.
+- The server has always computed it and told nobody. A field test read its
+  absence in a downstream response as "no trimming happened" — a different claim
+  from "nobody reports this" — and retired a live hypothesis on that reading.
+  Always present, `true` or `false`: a flag that appears on only one branch
+  cannot separate "it did not happen" from "we did not look".
+- Additive; nothing else on the deliberation surface moved.
+
 ## 0.25.1
 
 - **Docs links now resolve.** The README sent readers to `docs/*.md` "in the Pouchy

package/README.md

@@ -158,8 +158,17 @@ if (p.status !== 'ready') return renderStartFresh();     // narrow FIRST
 renderScene(p.checkpoint.currentScene);                  // may be null
 renderCounts(p.checkpoint.completedNodeCount, p.checkpoint.declaredNodeCount);
 renderDirections(p.checkpoint.nextOptions);
+renderPresence(p.checkpoint.publicFlags);                // 0.27.0 — always present
 ```
 
+**`publicFlags`** (0.27.0, Story Contract v4) carries the flags the author
+declared `public: true`, sorted by key, with the value the state this
+checkpoint reports — the declared initial when never set, `null` when there is
+neither. It is always present (an empty array for a story that publishes
+nothing), so a client can gate a character's presence on a runtime exit the
+story sets, rather than on a static scene list. Every other flag stays out of
+the checkpoint: a flag's name can itself be a spoiler.
+
 Narrowing on `status` is not politeness: the `unavailable` arm has no
 `checkpoint` key, so skipping the check reads `undefined` rather than telling a
 reader they never started a story they are halfway through.

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.25.1";
+export declare const WORLD_SDK_VERSION = "0.27.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. */
@@ -30,6 +30,16 @@ export interface WorldDeliberationResponse {
     /** Why it stopped. A run that hit a ceiling says so rather than letting a
      *  short list pass for a complete one. */
     stop: 'complete' | 'candidate_cap' | 'model_call_cap' | 'token_cap' | 'time_cap' | 'no_roles';
+    /** True when the role's view had to be trimmed to fit the previewer's input
+     *  budget — which grows with the worldline, so a long session can reach it
+     *  where a short one never does.
+     *
+     *  It matters because a previewer working from a cut-down view is not the
+     *  same instrument as one that saw the whole state, and until 0.26.0 the
+     *  server computed this and told nobody. A field test then read its absence
+     *  as "no trimming happened" — a different claim from "nobody reports this"
+     *  — and retired a live hypothesis on it. Always present, true or false. */
+    viewTrimmed: boolean;
 }
 /** The refusal classes a world call can produce. `unknown` is deliberate: an
  *  unrecognized status is never quietly folded into a neighbour. */
@@ -234,6 +244,17 @@ export interface WorldProgressCheckpointV1 {
         descriptor: string;
     }>;
     publicRelationsTruncated: boolean;
+    /** Story Contract v4 (0.27.0). The flags the pinned story declared
+     *  `public: true`, sorted by key, with the value the state THIS checkpoint
+     *  reports — the declared initial when never set, `null` when there is
+     *  neither. ALWAYS present (an empty array for a story that publishes
+     *  nothing), so absent never reads as unknown. A flag the author did not
+     *  mark public is never here: its name can be a spoiler. */
+    publicFlags: Array<{
+        key: string;
+        value: boolean | number | string | null;
+    }>;
+    publicFlagsTruncated: boolean;
     /** Newest first. That a beat happened — never what happened in it. */
     recentProgressRecords: Array<{
         seq: number;

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.25.1';
+export const WORLD_SDK_VERSION = '0.27.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.25.1",
+	"version": "0.27.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",