@pouchy_ai/world-sdk 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @pouchy_ai/world-sdk
 
+## 0.15.0
+
+- `getProgress()` — where a story is and whether it can go on, as a DERIVED
+  checkpoint over facts that already committed. Reads nothing into existence:
+  no new collection, no model call, no write.
+- The return is a discriminated union. `status: 'unavailable'` carries **no
+  `checkpoint`**, so code that forgets to narrow fails loudly instead of reading
+  a plausible zero; `resumable` is typed `false` on that arm.
+- `reason` is coarse on purpose. `world_unavailable` covers "no such instance",
+  "no access", "package revoked", "package gone" and "contract too new" as one
+  word — telling them apart would let a caller map which objects exist by
+  reading refusals. `story_reference_invalid` is distinct and leaks nothing: the
+  pinned story and its state disagree.
+- The checkpoint pins its provenance — `environmentRevision`, and the story
+  package's exact `revision` + `contentHash`. It follows the INSTANCE's pin, so
+  publishing a new story revision never changes what a running world reports.
+- **`declaredNodeCount` is not a denominator.** A branching story never visits
+  every declared node; there is no percentage field and `completedNodeCount /
+  declaredNodeCount` is not a completion ratio. Show two numbers.
+- **`recentProgressRecords` is not a summary.** `{ seq, kind, at }` says a beat
+  happened, never what happened in it. Read `/turns` for the lines.
+- `nextOptions` is the same shape and the same derivation the live turn uses —
+  never model-generated, capped server-side.
+- Two reads of an unchanged world are byte-identical: no read-time clock, every
+  list explicitly ordered, state and ledger taken in one read-only transaction.
+
+## 0.14.0
+
+- `deliberate()` and `selectCandidate()` — ask for a few PUBLIC directions a
+  beat could take, then commit the one the player chose.
+- Candidates are safe to render straight to a player: `candidateId`, `title`,
+  `direction`, `shortTeaser`, `participatingRoles` and nothing else. No
+  reasoning, no role secrets, no simulated effects, no scores.
+- `selectCandidate` commits through the ordinary coordinator — same beat, same
+  ledger, same `WorldTurnResult`. A deliberation has no privileges over the
+  world: its simulated effects are never carried into the real turn.
+- The `envelope` is opaque and belongs on your SERVER. Hand it back unchanged;
+  do not send it to a browser. The turn id is fixed inside it, so re-sending the
+  same envelope retries rather than committing a second beat.
+- If the world moved since the candidates were produced, `selectCandidate`
+  answers 409 `stale_deliberation` having spent nothing — deliberate again.
+- Off unless the world's published revision declares `deliberation`. A world
+  without it answers 409 on `deliberate()`, which simply means that story plays
+  directly.
+
 ## 0.13.0
 
 - `createWorldSession` now returns a typed `WorldSessionResponse` instead of

package/README.md

@@ -47,8 +47,12 @@ const world = new PouchyWorldClient({
 
 **Running** — `createWorldSession`, `runTurn`, `sendEvent`.
 
-**Reading** — `getWorldState`, `getTurn`, `listTurns`, `listTurnsSince`,
-`replayLedger`, `replayLedgerToEnd`.
+**Deliberating** — `deliberate`, `selectCandidate`. Ask for a couple of public
+directions a beat could take, then commit the one the player picked. Off unless
+the world's published revision declares it; the `envelope` is server-side only.
+
+**Reading** — `getWorldState`, `getProgress`, `getTurn`, `listTurns`,
+`listTurnsSince`, `replayLedger`, `replayLedgerToEnd`.
 
 **Which credential does what.** This matters more than it looks: one of them
 expires within the hour.
@@ -109,6 +113,27 @@ Both are additive: a turn committed before world API 1.6 carries none of the
 four turn-time facts (`selectedRoles`, `skippedRoles`, `repairs`,
 `nextOptions`). Absent means UNKNOWN, never "none".
 
+**Reopening a story.** `getProgress` answers the question a returning reader's
+client has — where was I, and can I go on? — without replaying anything.
+
+```ts
+const p = await world.getProgress(envId, instanceId);
+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);
+```
+
+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.
+
+Two shapes it does not have. **`declaredNodeCount` is not a denominator** — a
+branching story never visits every node the author declared, so show the two
+counts, never a percentage. And **`recentProgressRecords` is not a summary**:
+`{ seq, kind, at }` says a beat happened, not what happened in it; the lines
+live behind `getTurn` / `listTurns`.
+
 **Content return** — `createScriptDraft`, `getScriptDraft`, `listScriptDrafts`,
 `reviewScriptDraft`, `exportScriptDraft`.
 

package/dist/index.d.ts

@@ -4,8 +4,33 @@
  *  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.13.0";
+export declare const WORLD_SDK_VERSION = "0.15.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. */
+export interface WorldDeliberationCandidate {
+    candidateId: string;
+    title: string;
+    /** What the scene will be steered toward. Public, because the player is
+     *  choosing it and must be able to read what they are choosing. */
+    direction: string;
+    shortTeaser: string;
+    participatingRoles: string[];
+}
+export interface WorldDeliberationResponse {
+    candidates: WorldDeliberationCandidate[];
+    /** Signed evidence. Opaque — hand it back to `selectCandidate` unchanged. */
+    envelope: string;
+    expiresAt: number;
+    budgetSpent: {
+        modelCalls: number;
+        tokens: number;
+        ms: number;
+    };
+    /** 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';
+}
 /** The refusal classes a world call can produce. `unknown` is deliberate: an
  *  unrecognized status is never quietly folded into a neighbour. */
 export declare const WORLD_ERROR_CODES: readonly ["unauthorized", "forbidden", "not_found", "conflict", "unprocessable", "rate_limited", "payload_too_large", "server_error", "network", "unknown"];
@@ -131,6 +156,68 @@ export interface WorldTurnResult {
  *
  *  The four turn-time facts are optional because rows committed before world
  *  API 1.6 do not carry them. Absent means UNKNOWN. */
+/** Where a story is, and whether it can go on. World API 1.18.
+ *
+ *  A DISCRIMINATED UNION, not an optional-field bag. The `unavailable` arm has
+ *  no `checkpoint` key at all, so narrowing on `status` is not a style choice:
+ *  it is the only way to reach the data, and code that skips it fails loudly
+ *  instead of reading a plausible zero. `resumable` is typed `false` on that
+ *  arm, so "unavailable but resumable" cannot be constructed. */
+export type WorldProgressResponse = {
+    status: 'ready';
+    resumable: boolean;
+    checkpoint: WorldProgressCheckpointV1;
+} | {
+    status: 'unavailable';
+    resumable: false;
+    reason: WorldProgressUnavailableReason;
+};
+/** `world_unavailable` is deliberately coarse — no such instance, no access, a
+ *  revoked or deleted package, a contract too new to read. Distinguishing them
+ *  would let a caller map which internal objects exist by reading refusals.
+ *  `story_reference_invalid` is different in kind: the pinned story and the
+ *  state it is pinned to disagree, which reveals nothing about existence. */
+export type WorldProgressUnavailableReason = 'world_unavailable' | 'story_reference_invalid';
+export interface WorldProgressCheckpointV1 {
+    contractVersion: 1;
+    /** The revision this INSTANCE is pinned to for life. */
+    environmentRevision: number;
+    storyPackageRef: {
+        packageId: string;
+        revision: number;
+        contentHash: string;
+    };
+    stateRevision: number;
+    started: boolean;
+    /** Null when no scene has been opened. Never a substitute for one the
+     *  pinned story does not declare — that answers `story_reference_invalid`. */
+    currentScene: {
+        sceneId: string;
+        title: string;
+    } | null;
+    completedNodeCount: number;
+    /** What the AUTHOR declared. NOT a denominator: a branching story never
+     *  visits every node, so `completedNodeCount / declaredNodeCount` is not a
+     *  completion ratio. Render them as two numbers. */
+    declaredNodeCount: number;
+    publicRelations: Array<{
+        between: [string, string];
+        descriptor: string;
+    }>;
+    publicRelationsTruncated: boolean;
+    /** Newest first. That a beat happened — never what happened in it. */
+    recentProgressRecords: Array<{
+        seq: number;
+        kind: 'turn' | 'event' | 'system';
+        at: number;
+    }>;
+    recentProgressTruncated: boolean;
+    nextOptions: Array<{
+        branchId: string;
+        condition: string;
+    }>;
+    rebuildable: true;
+}
 export interface WorldTurnReadback {
     turnId: string;
     worldInstanceId: string;
@@ -605,6 +692,26 @@ export declare class PouchyWorldClient {
         environmentRevision: number;
         state: Record<string, unknown>;
     }>;
+    /** Where the story is, and whether it can go on. World API 1.18.
+     *
+     *  A DERIVED checkpoint: nothing is stored to answer it, no model is asked,
+     *  and the story it reports is the package this INSTANCE pinned, at its
+     *  exact revision and content hash — never whatever was published since.
+     *
+     *  Check `status` before reading anything else. `unavailable` has no
+     *  `checkpoint` at all, which is deliberate: a caller that skips the check
+     *  gets `undefined` rather than a plausible zero. Its `reason` is
+     *  intentionally coarse — one word covers "no such instance", "no access",
+     *  "package revoked", "package gone" and "contract too new", because telling
+     *  them apart would let a caller map which objects exist by reading errors.
+     *
+     *  Two things it does NOT give you. There is no completion percentage:
+     *  `declaredNodeCount` is what the AUTHOR wrote, and a branching story never
+     *  visits all of it, so a ratio of the two counts is meaningless — show them
+     *  as two numbers. And `recentProgressRecords` says a beat happened, not
+     *  what happened in it; for the lines themselves, read the timeline.
+     */
+    getProgress(environmentId: string, worldInstanceId: string): Promise<WorldProgressResponse>;
     /** Read back a COMMITTED turn. The recovery path when a response was lost:
      *  it re-runs nothing, and a 404 means the turn never committed. */
     /** Read a COMMITTED turn back — the recovery path when a response was lost.
@@ -811,6 +918,35 @@ export declare class PouchyWorldClient {
          *  role's private notes. */
         proposedPatches?: readonly Record<string, unknown>[];
     }): Promise<WorldTurnResult>;
+    /** Ask for a few PUBLIC directions this beat could take, without taking it.
+     *
+     *  Off unless the world's published revision declares `deliberation`. Nothing
+     *  is written and no candidate is stored: what comes back is a short list
+     *  plus a signed `envelope` you hand to `selectCandidate`. The candidates are
+     *  public by construction — no reasoning, no role secrets, no simulated
+     *  effects — so they are safe to render straight to a player. */
+    deliberate(input: {
+        environmentId: string;
+        worldInstanceId: string;
+        requestId?: string;
+        text: string;
+        model?: string;
+    }): Promise<WorldDeliberationResponse>;
+    /** Commit the direction the player chose. This IS an ordinary beat — the
+     *  same coordinator, the same ledger, the same result shape.
+     *
+     *  Re-send the same `envelope` to retry: the turn id is fixed inside it, so a
+     *  second call is a duplicate rather than a second beat. If the world moved
+     *  since the candidates were produced, this answers 409 `stale_deliberation`
+     *  and spends nothing — deliberate again. */
+    selectCandidate(input: {
+        environmentId: string;
+        worldInstanceId: string;
+        envelope: string;
+        candidateId: string;
+        direction: string;
+        text: string;
+    }): Promise<WorldTurnResult>;
     /** Send a trusted EVENT into a world. On a `coordinated` world this becomes
      *  one coordinator turn; on an `actor` world it wakes each subscribed role.
      *  Either way `eventId` is the dedupe key — re-send it freely. */

package/dist/index.js

@@ -23,9 +23,24 @@ 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.13.0';
+export const WORLD_SDK_VERSION = '0.15.0';
 export const DEFAULT_BASE_URL = 'https://pouchy.ai/v1';
-// ── errors ─────────────────────────────────────────────────────────────────
+/** 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
+ *  signature is not needed to read it, and reading it proves nothing — the
+ *  SERVER verifies. This is only so the client signs the right slot. */
+function commitTurnIdOf(envelope) {
+    const payload = envelope.slice(0, envelope.lastIndexOf('.'));
+    try {
+        const json = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+        if (typeof json.commitTurnId === 'string' && json.commitTurnId)
+            return json.commitTurnId;
+    }
+    catch {
+        /* fall through */
+    }
+    throw new Error('deliberation envelope is malformed — re-run deliberate()');
+}
 /** The refusal classes a world call can produce. `unknown` is deliberate: an
  *  unrecognized status is never quietly folded into a neighbour. */
 export const WORLD_ERROR_CODES = [
@@ -282,6 +297,28 @@ export class PouchyWorldClient {
     getWorldState(environmentId, worldInstanceId) {
         return this.read(`/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/state`, `/admin/environments/${environmentId}/instances/${worldInstanceId}/state`);
     }
+    /** Where the story is, and whether it can go on. World API 1.18.
+     *
+     *  A DERIVED checkpoint: nothing is stored to answer it, no model is asked,
+     *  and the story it reports is the package this INSTANCE pinned, at its
+     *  exact revision and content hash — never whatever was published since.
+     *
+     *  Check `status` before reading anything else. `unavailable` has no
+     *  `checkpoint` at all, which is deliberate: a caller that skips the check
+     *  gets `undefined` rather than a plausible zero. Its `reason` is
+     *  intentionally coarse — one word covers "no such instance", "no access",
+     *  "package revoked", "package gone" and "contract too new", because telling
+     *  them apart would let a caller map which objects exist by reading errors.
+     *
+     *  Two things it does NOT give you. There is no completion percentage:
+     *  `declaredNodeCount` is what the AUTHOR wrote, and a branching story never
+     *  visits all of it, so a ratio of the two counts is meaningless — show them
+     *  as two numbers. And `recentProgressRecords` says a beat happened, not
+     *  what happened in it; for the lines themselves, read the timeline.
+     */
+    getProgress(environmentId, worldInstanceId) {
+        return this.read(`/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/progress`, `/admin/environments/${environmentId}/instances/${worldInstanceId}/progress`);
+    }
     /** Read back a COMMITTED turn. The recovery path when a response was lost:
      *  it re-runs nothing, and a 404 means the turn never committed. */
     /** Read a COMMITTED turn back — the recovery path when a response was lost.
@@ -521,6 +558,39 @@ export class PouchyWorldClient {
         };
         return this.signed(`/projects/${this.projectId}/environments/${input.environmentId}/instances/${input.worldInstanceId}/turns`, body, turnId);
     }
+    /** Ask for a few PUBLIC directions this beat could take, without taking it.
+     *
+     *  Off unless the world's published revision declares `deliberation`. Nothing
+     *  is written and no candidate is stored: what comes back is a short list
+     *  plus a signed `envelope` you hand to `selectCandidate`. The candidates are
+     *  public by construction — no reasoning, no role secrets, no simulated
+     *  effects — so they are safe to render straight to a player. */
+    deliberate(input) {
+        const requestId = input.requestId ?? newTurnId('dlb-req');
+        const body = { requestId, text: input.text, ...(input.model ? { model: input.model } : {}) };
+        return this.signed(`/projects/${this.projectId}/environments/${input.environmentId}/instances/${input.worldInstanceId}/deliberations`, body, 
+        // The signature's id slot is namespaced, so a deliberation signature
+        // can never be replayed onto the turn door.
+        `dlb:${requestId}`);
+    }
+    /** Commit the direction the player chose. This IS an ordinary beat — the
+     *  same coordinator, the same ledger, the same result shape.
+     *
+     *  Re-send the same `envelope` to retry: the turn id is fixed inside it, so a
+     *  second call is a duplicate rather than a second beat. If the world moved
+     *  since the candidates were produced, this answers 409 `stale_deliberation`
+     *  and spends nothing — deliberate again. */
+    selectCandidate(input) {
+        const body = {
+            envelope: input.envelope,
+            candidateId: input.candidateId,
+            direction: input.direction,
+            text: input.text
+        };
+        // The id slot is the turn id the envelope already fixed, so the signature
+        // covers the id the server will actually commit under.
+        return this.signed(`/projects/${this.projectId}/environments/${input.environmentId}/instances/${input.worldInstanceId}/deliberations/select`, body, commitTurnIdOf(input.envelope));
+    }
     /** Send a trusted EVENT into a world. On a `coordinated` world this becomes
      *  one coordinator turn; on an `actor` world it wakes each subscribed role.
      *  Either way `eventId` is the dedupe key — re-send it freely. */

package/package.json

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