@pouchy_ai/world-sdk 0.12.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # @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
+  `Record<string, unknown>`. The wire fields are unchanged — this names what the
+  server has always sent.
+- **The field is `session_token`, not `token`.** The untyped return let that
+  mistake compile: `conformance.mjs` asserted `session.token`, which the server
+  has never sent, so the session check threw against any real server while every
+  local gate stayed green. Typing the response is what stops it recurring; the
+  runner and both quickstarts were corrected to match.
+- `release-check.mjs` now compares `WORLD_SDK_VERSION` against the version of
+  the package it actually INSTALLED. The constant sat at `0.1.0` for eight
+  releases while the package shipped 0.8.0, so every request reported the wrong
+  client in its `user-agent`; the drift was corrected in 0.12.0, and this is the
+  gate that stops it recurring.
+- No method changed shape, and no request or response bytes changed.
+
 ## 0.12.0
 
 Additive: authoring joins the machine lane, so nothing in an integration needs
@@ -54,7 +116,7 @@ Additive: your backend can tell the world what it already knows. World API 1.8.
 
 Additive: an unattended backend can now read its own world. World API 1.7.
 
-- New `adminKey` client option — a project admin key (`pak_…`), minted once from
+- New `adminKey` client option — a project admin key (`pchy_admin_…`), minted once from
   the dashboard, long-lived and machine-held. When present, the world READS
   (`getWorldState`, `listTurns`, `listTurnsSince`, `getTurn`, `getWorldMetrics`,
   `listDeliveries`) go to a new `/v1/admin/environments/**` mirror instead of the

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.
@@ -56,7 +60,7 @@ expires within the hour.
 | you hold | you can | you cannot |
 |---|---|---|
 | `secretKey` + `signing` | mint sessions, drive turns, send events | read anything back |
-| `adminKey` (`pak_…`, long-lived) | author story packages and worlds; read the world: overview, state, timeline, turn read-back, metrics, delivery queue, cost | drive a turn, act on the delivery queue, run the content loop |
+| `adminKey` (`pchy_admin_…`, long-lived) | author story packages and worlds; read the world: overview, state, timeline, turn read-back, metrics, delivery queue, cost | drive a turn, act on the delivery queue, run the content loop |
 | `adminToken` (Firebase ID token, ~1h) | everything above plus the content loop | outlive the hour |
 
 A server holds `secretKey` + `signing` + `adminKey` and needs **no browser login
@@ -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`.
 
@@ -157,16 +182,46 @@ an `approved` editorial can be exported.
 `newTurnId` / `isReservedTurnId` (idempotency), `describeTurn` (read a result
 without guessing), `WorldApiError` with typed codes and `.retryable`.
 
+## When a signed door refuses you
+
+All three signed doors answer one uniform 403 on a bad signature — they will
+never tell you which of the four things is wrong, because an endpoint that
+names the failing credential is an oracle. The reason lives in the project's own
+audit trail instead:
+
+```
+GET https://pouchy.ai/v1/projects/{projectId}/environments/{envId}/preflight
+Authorization: Bearer <OwnerToken>
+```
+
+**That is an OwnerToken — a signed-in project admin's Firebase ID token, not the
+Secret Key this client holds**, and not the Admin key either (preflight is
+deliberately absent from the `/admin` mirror). There is no SDK method for it for
+the same reason: it answers a question a developer asks once while looking at
+the dashboard, not one a backend asks in a loop.
+
+It returns the recent refusals with a closed reason vocabulary — `missing`,
+`malformed`, `unknown_key`, `stale`, `bad_signature`, `no_keys` — plus how many
+audit rows it scanned, because an empty feed is not a clean bill of health.
+
+`docs/world-sdk-errors.md` in the Pouchy repo maps every reason and every
+`WorldApiError` code to what to change.
+
 ## The three things integrators get wrong
 
 **1. Turn ids are the idempotency key.** Mint one per BEAT and re-send the same
 one to retry. A new id is a new beat: it will run the models again and commit
 again. `newTurnId()` exists so this is a deliberate choice rather than a habit.
 
-**2. Sign the bytes you send.** `signSourceRequest` hashes the exact body
-string. Serializing twice — once to sign, once to send — signs bytes you did
-not send, and the server will (correctly) refuse them. This client always signs
-the string it is about to write.
+**2. Sign the bytes you send, with the door's own id slot.** `signSourceRequest`
+hashes the exact body string. Serializing twice — once to sign, once to send —
+signs bytes you did not send, and the server will (correctly) refuse them. This
+client always signs the string it is about to write. The fourth canonical line
+is the ID SLOT, and it differs per door: `turnId` on the turns door, `eventId`
+on `/events`, and the body's own `world.request_id` on `/sessions` — a session
+mint has neither a turn nor an event. `createWorldSession` passes it for you; if you
+are signing by hand there, an invented or empty id verifies locally and comes
+back `bad_signature`, which reads exactly like a wrong secret.
 
 **3. Execution and delivery are different questions.** `executionStatus` says
 whether the world moved; `deliveryStatus` says whether the audience has heard

package/conformance.mjs

@@ -184,9 +184,12 @@ await check('session mint binds one user to one role (machine lane)', async () =
 		role: scenario.leadRole,
 		externalUserId: `conformance-${scenarioName}-${stamp}`
 	});
-	instanceId = session?.world?.instance ?? session?.world?.world_instance;
+	// The wire names, exactly as the server sends them (`WorldSessionResponse`).
+	// This check used to read `session.token`, which the server has never sent —
+	// so it threw against every real server while every local gate stayed green.
+	instanceId = session?.world?.instance;
 	if (!instanceId) throw new Error('no world instance in the session payload');
-	if (!session.token) throw new Error('no session token minted');
+	if (!session?.session_token) throw new Error('no session token minted (expected session_token)');
 	return instanceId;
 });
 

package/dist/index.d.ts

@@ -1,5 +1,36 @@
-export declare const WORLD_SDK_VERSION = "0.12.0";
+/** Kept in step with `package.json` by `release-check.mjs`, which compares this
+ *  constant against the version of the package it actually INSTALLED. It rides
+ *  the `user-agent` of every request, so a drift here misreports which client
+ *  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.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"];
@@ -26,7 +57,7 @@ export declare const SOURCE_SIGNATURE_HEADER = "X-Pouchy-Source-Signature";
 /** Build the `X-Pouchy-Source-Signature` header for one request body.
  *
  *  The canonical string is five newline-joined lines — scheme, unix seconds,
- *  the declared source, the event/turn id, and the sha256 of the EXACT body
+ *  the declared source, the door's id slot (see `id`), and the sha256 of the EXACT body
  *  bytes. Sign at SEND time, every attempt: a legitimate retry of the same id
  *  days later carries a fresh timestamp and passes the ±5 minute skew, because
  *  the signature proves origin and never doubles as a dedupe key.
@@ -36,7 +67,11 @@ export declare const SOURCE_SIGNATURE_HEADER = "X-Pouchy-Source-Signature";
  *  send. */
 export declare function signSourceRequest(input: {
     source: string;
-    /** eventId for `/events`, turnId for the turns door — the id slot. */
+    /** The id slot, which is per-door: `turnId` for the turns door, `eventId`
+     *  for `/events`, and the request's own `world.request_id` for `/sessions`
+     *  (`createWorldSession` passes it for you). A mint has neither a turn nor an
+     *  event, so signing an empty or invented id there is the classic first
+     *  failure — it verifies locally and is refused as `bad_signature`. */
     id: string;
     body: string;
     keyId: string;
@@ -121,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;
@@ -470,6 +567,43 @@ export interface ApprovedScriptExportRow {
     deliveryAttempted?: number;
     deliveryOk?: number;
 }
+/** What `POST /v1/sessions` actually returns for a WORLD mint.
+ *
+ *  Typed because it was untyped: `createWorldSession` used to answer
+ *  `Record<string, unknown>`, so a caller reading `session.token` — a field the
+ *  server has never sent — compiled, shipped, and failed only against a live
+ *  server. The wire is snake_case and stays that way here; renaming it in the
+ *  client would put a second vocabulary between an integrator and the HTTP
+ *  responses they read in their own logs.
+ *
+ *  `world` is present because `createWorldSession` always sends a world block;
+ *  an ordinary (non-world) mint omits it, and that lane is not this method's. */
+export interface WorldSessionResponse {
+    /** The end-user session token. Hand it to YOUR frontend, which drives it with
+     *  `@pouchy_ai/companion-sdk`. Scoped to one instance and one role, and
+     *  carries no project credential. NOT named `token`. */
+    readonly session_token: string;
+    /** Seconds. The server clamps a requested ttl into [300, 86400]; this is the
+     *  clamped value, not what you asked for. */
+    readonly expires_in: number;
+    /** The agent the ROLE resolved to. The world decides it — passing an agent to
+     *  a world mint is refused. */
+    readonly agent: string;
+    readonly instance: {
+        readonly id: string;
+        readonly external_user_id: string;
+        /** True the first time this end user was provisioned. */
+        readonly created: boolean;
+    };
+    readonly world: {
+        readonly environment: string;
+        /** The revision this instance is PINNED to — for life. */
+        readonly environment_revision: number;
+        /** The world instance id to drive turns against. */
+        readonly instance: string;
+        readonly role: string;
+    };
+}
 export interface WorldClientOptions {
     /** The project this client acts for. */
     projectId: string;
@@ -480,7 +614,7 @@ export interface WorldClientOptions {
      *  browser sign-in. Fine for a script a person is watching; wrong for a
      *  server. For a server, use `adminKey`. */
     adminToken?: string;
-    /** A project ADMIN key (`pak_…`), minted once from the dashboard.
+    /** A project ADMIN key (`pchy_admin_…`), minted once from the dashboard.
      *
      *  Long-lived and machine-held: this is what an unattended backend uses.
      *  When present, the world READS (overview, state, timeline, turn read-back,
@@ -558,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.
@@ -740,7 +894,7 @@ export declare class PouchyWorldClient {
         externalUserId: string;
         worldInstance?: string;
         requestId?: string;
-    }): Promise<Record<string, unknown>>;
+    }): Promise<WorldSessionResponse>;
     /** Drive ONE coordinated beat. `turnId` is the idempotency key: re-send the
      *  same one to retry, mint a new one for a new beat. */
     runTurn(input: {
@@ -764,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

@@ -17,9 +17,30 @@
 // SIGNING a request the way the server verifies it, and choosing turn ids that
 // make a retry idempotent instead of a second beat.
 import { createHash, createHmac, randomUUID } from 'node:crypto';
-export const WORLD_SDK_VERSION = '0.12.0';
+/** Kept in step with `package.json` by `release-check.mjs`, which compares this
+ *  constant against the version of the package it actually INSTALLED. It rides
+ *  the `user-agent` of every request, so a drift here misreports which client
+ *  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.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 = [
@@ -111,7 +132,7 @@ const SOURCE_SIGNATURE_SCHEME = 'POUCHY-SOURCE-V1';
 /** Build the `X-Pouchy-Source-Signature` header for one request body.
  *
  *  The canonical string is five newline-joined lines — scheme, unix seconds,
- *  the declared source, the event/turn id, and the sha256 of the EXACT body
+ *  the declared source, the door's id slot (see `id`), and the sha256 of the EXACT body
  *  bytes. Sign at SEND time, every attempt: a legitimate retry of the same id
  *  days later carries a fresh timestamp and passes the ±5 minute skew, because
  *  the signature proves origin and never doubles as a dedupe key.
@@ -276,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.
@@ -515,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.12.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",