@pouchy_ai/world-sdk 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @pouchy_ai/world-sdk
 
+## 0.9.0
+
+Additive: the read-back becomes a real recovery path, and the timeline gets a
+resume cursor. World API 1.6.
+
+- `getTurn` now returns a typed `WorldTurnReadback` instead of an opaque
+  record, and the server fills in the four turn-time facts the live result
+  always had and the read-back never did: `selectedRoles`, `skippedRoles`,
+  `repairs` and `nextOptions`. Recovering a lost response used to tell you what
+  the world changed and not what it offered next, which made resuming a story
+  guesswork. All four are optional — a turn committed before this release
+  carries none of them, and absence means UNKNOWN, not "none".
+- Two divergences from `WorldTurnResult` are deliberate and now typed rather
+  than implied: a read-back's `completionStatus`/`executionStatus` are the
+  constant `'committed'` (a turn that never committed has no entry and answers
+  404), and its `deliveryStatus` adds `'unknown'` (once settled rows are
+  reaped, the absence of a queue row is not proof of delivery).
+- New `listTurns(environmentId, worldInstanceId, { limit, sinceSeq })` returning
+  a `WorldTimelinePage`. With `sinceSeq` you get the beats AFTER that revision,
+  oldest first, plus `nextSinceSeq` to continue; without it you get the
+  newest-first window as before. The response names its own `order`.
+- New `listTurnsSince(...)` — follows that cursor to the end. This is the resume
+  primitive: a backend that stored the last `seq` it handled gets exactly the
+  beats it missed, in order, with no gap at a page boundary and no beat twice.
+  Bounded by `maxPages`, because an unbounded follow loop against a busy world
+  never returns.
+- The API document is now served at `GET https://pouchy.ai/v1/world/openapi` —
+  public, unauthenticated, and previously reachable by nobody.
+- No existing method changed shape.
+
 ## 0.8.0
 
 - `WorldDeliveryOpsRow` gained `cleanupRetryCount` and `cleanupStalledAt`.

package/README.md

@@ -47,7 +47,22 @@ const world = new PouchyWorldClient({
 
 **Running** — `createWorldSession`, `runTurn`, `sendEvent`.
 
-**Reading** — `getWorldState`, `getTurn`, `replayLedger`, `replayLedgerToEnd`.
+**Reading** — `getWorldState`, `getTurn`, `listTurns`, `listTurnsSince`,
+`replayLedger`, `replayLedgerToEnd`.
+
+**Resuming after a crash.** `getTurn` returns the same fields the live result
+did — `nextOptions` included — so a recovered session can offer the audience
+the choices it was about to. To catch up on beats you missed entirely, store
+the last `seq` you processed and call `listTurnsSince`:
+
+```ts
+const missed = await world.listTurnsSince(envId, instanceId, lastSeqIHandled);
+for (const beat of missed) render(beat);   // in order, no gap, no repeat
+```
+
+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".
 
 **Content return** — `createScriptDraft`, `getScriptDraft`, `listScriptDrafts`,
 `reviewScriptDraft`, `exportScriptDraft`.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const WORLD_SDK_VERSION = "0.1.0";
+export declare const WORLD_SDK_VERSION = "0.9.0";
 export declare const DEFAULT_BASE_URL = "https://pouchy.ai/v1";
 /** The refusal classes a world call can produce. `unknown` is deliberate: an
  *  unrecognized status is never quietly folded into a neighbour. */
@@ -106,6 +106,102 @@ export interface WorldTurnResult {
 /** Why a redacted dead letter could not be rebuilt. A closed vocabulary: an
  *  operator deciding whether to resolve a gap is making a judgement call, and a
  *  free-text reason is one they cannot compare across incidents. */
+/** What `GET …/turns/{turnId}` answers. The live result's fields, plus what
+ *  only the record knows (when it committed, which revision it bound to, how
+ *  its lines were delivered).
+ *
+ *  Two deliberate differences from `WorldTurnResult`, both because a read-back
+ *  exists ONLY for a turn that committed:
+ *
+ *    · `completionStatus` / `executionStatus` are the constant `'committed'`,
+ *      not a member of the live union. A turn that never committed has no entry
+ *      and answers 404 — there is no status to report;
+ *    · `deliveryStatus` adds `'unknown'`, which is a real answer once settled
+ *      rows have been reaped: no queue row is not proof of delivery.
+ *
+ *  The four turn-time facts are optional because rows committed before world
+ *  API 1.6 do not carry them. Absent means UNKNOWN. */
+export interface WorldTurnReadback {
+    turnId: string;
+    worldInstanceId: string;
+    beforeStateRevision: number;
+    afterStateRevision: number;
+    roleMessages: Array<{
+        roleId: string;
+        message: string;
+    }>;
+    committedStateDiff: unknown[];
+    rejectedEffects: Array<{
+        index: number;
+        reason: string;
+        roleId?: string;
+        kind?: string;
+    }>;
+    selectedRoles?: string[];
+    skippedRoles?: Array<{
+        roleId: string;
+        reason: string;
+    }>;
+    repairs?: Array<{
+        roleId: string;
+        outcome: 'repaired' | 'fallback';
+        reason?: string;
+    }>;
+    nextOptions?: Array<{
+        branchId: string;
+        condition: string;
+    }>;
+    committedAt: number;
+    environmentRevision: number;
+    storyPackageRef?: {
+        packageId: string;
+        revision: number;
+        contentHash: string;
+    };
+    eventId?: string;
+    traceId?: string;
+    completionStatus: 'committed';
+    executionStatus: 'committed';
+    deliveryStatus: WorldDeliveryStatus | 'unknown';
+    deliveryGaps?: unknown[];
+    deliveryCounts?: {
+        total: number;
+        delivered: number;
+        [k: string]: number;
+    };
+}
+/** One page of the committed timeline. `order` says which way it runs, because
+ *  the two calls answer different questions: without a cursor you get the
+ *  newest beats first, with one you get everything after it, oldest first. */
+export interface WorldTimelinePage {
+    beats: Array<{
+        entryId: string;
+        seq: number;
+        kind: string;
+        actorRoleId: string | null;
+        beforeRevision: number;
+        afterRevision: number;
+        patchCount: number;
+        committedAt: number;
+        turnId: string | null;
+        messages: Array<{
+            roleId: string;
+            text: string;
+            fallback?: true;
+        }>;
+        effects: Array<{
+            kind: string;
+            roleId: string;
+            target: string | null;
+            accepted: boolean;
+            code?: WorldRejectionCode;
+            reason?: string;
+        }>;
+    }>;
+    order: 'asc' | 'desc';
+    /** Present only on a cursor read: pass it back as `sinceSeq` to continue. */
+    nextSinceSeq?: number | null;
+}
 export type WorldRehydrateFailure = 'source_missing' | 'archive_unavailable' | 'hash_mismatch' | 'ledger_drift' | 'identity_mismatch';
 /** What to DO about a stuck delivery, in one call. The three answers are the
  *  three verbs, in the order they should be tried: re-send what is still there,
@@ -448,10 +544,38 @@ export declare class PouchyWorldClient {
     }>;
     /** 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. */
-    getTurn(environmentId: string, worldInstanceId: string, turnId: string): Promise<Record<string, unknown>>;
+    /** Read a COMMITTED turn back — the recovery path when a response was lost.
+     *
+     *  As of world API 1.6 this carries the same fields the live result did,
+     *  `nextOptions` included, so a resumed session can offer the audience the
+     *  same choices it would have. Rows committed before that carry none of the
+     *  four turn-time facts: absent means UNKNOWN, never "none". */
+    getTurn(environmentId: string, worldInstanceId: string, turnId: string): Promise<WorldTurnReadback>;
     /** Verify that the materialized state is what the committed ledger says.
      *  Always a dry run — it reports, it never repairs. Pass the previous
      *  report's `cursor` to continue a run that came back `incomplete`. */
+    /** ONE page of the committed timeline.
+     *
+     *  Pass `sinceSeq` to resume: you get the beats after it, oldest first, and
+     *  a `nextSinceSeq` to continue with. Without it you get the newest-first
+     *  window, which is the "what happened lately" view and cannot be paged
+     *  past its cap. */
+    listTurns(environmentId: string, worldInstanceId: string, opts?: {
+        limit?: number;
+        sinceSeq?: number;
+    }): Promise<WorldTimelinePage>;
+    /** Walk the timeline FORWARD from a revision already processed, following
+     *  the cursor to the end. The resume primitive: a backend that stored the
+     *  last `seq` it handled calls this once on restart and receives exactly the
+     *  beats it missed, in order, with no gap at a page boundary and no beat
+     *  twice.
+     *
+     *  `maxPages` is a stop, not a tuning knob — an unbounded follow loop
+     *  against a busy world never returns. */
+    listTurnsSince(environmentId: string, worldInstanceId: string, sinceSeq: number, opts?: {
+        pageSize?: number;
+        maxPages?: number;
+    }): Promise<WorldTimelinePage['beats']>;
     replayLedger(environmentId: string, worldInstanceId: string, options?: {
         cursor?: string;
         maxEntries?: number;

package/dist/index.js

@@ -17,7 +17,7 @@
 // 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.1.0';
+export const WORLD_SDK_VERSION = '0.9.0';
 export const DEFAULT_BASE_URL = 'https://pouchy.ai/v1';
 // ── errors ─────────────────────────────────────────────────────────────────
 /** The refusal classes a world call can produce. `unknown` is deliberate: an
@@ -275,12 +275,63 @@ export class PouchyWorldClient {
     }
     /** 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.
+     *
+     *  As of world API 1.6 this carries the same fields the live result did,
+     *  `nextOptions` included, so a resumed session can offer the audience the
+     *  same choices it would have. Rows committed before that carry none of the
+     *  four turn-time facts: absent means UNKNOWN, never "none". */
     getTurn(environmentId, worldInstanceId, turnId) {
         return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/turns/${encodeURIComponent(turnId)}`);
     }
     /** Verify that the materialized state is what the committed ledger says.
      *  Always a dry run — it reports, it never repairs. Pass the previous
      *  report's `cursor` to continue a run that came back `incomplete`. */
+    /** ONE page of the committed timeline.
+     *
+     *  Pass `sinceSeq` to resume: you get the beats after it, oldest first, and
+     *  a `nextSinceSeq` to continue with. Without it you get the newest-first
+     *  window, which is the "what happened lately" view and cannot be paged
+     *  past its cap. */
+    listTurns(environmentId, worldInstanceId, opts) {
+        const q = new URLSearchParams();
+        if (opts?.limit !== undefined)
+            q.set('limit', String(opts.limit));
+        if (opts?.sinceSeq !== undefined)
+            q.set('sinceSeq', String(opts.sinceSeq));
+        const suffix = q.toString() ? `?${q}` : '';
+        return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/turns${suffix}`);
+    }
+    /** Walk the timeline FORWARD from a revision already processed, following
+     *  the cursor to the end. The resume primitive: a backend that stored the
+     *  last `seq` it handled calls this once on restart and receives exactly the
+     *  beats it missed, in order, with no gap at a page boundary and no beat
+     *  twice.
+     *
+     *  `maxPages` is a stop, not a tuning knob — an unbounded follow loop
+     *  against a busy world never returns. */
+    async listTurnsSince(environmentId, worldInstanceId, sinceSeq, opts) {
+        const pageSize = opts?.pageSize ?? 50;
+        const maxPages = opts?.maxPages ?? 20;
+        const out = [];
+        let cursor = sinceSeq;
+        for (let page = 0; page < maxPages; page++) {
+            const got = await this.listTurns(environmentId, worldInstanceId, {
+                limit: pageSize,
+                sinceSeq: cursor
+            });
+            if (!got.beats.length)
+                break;
+            out.push(...got.beats);
+            const next = got.nextSinceSeq;
+            // Defensive: a server that stopped advancing the cursor would other-
+            // wise spin here re-reading the same page until maxPages.
+            if (typeof next !== 'number' || next <= cursor)
+                break;
+            cursor = next;
+        }
+        return out;
+    }
     replayLedger(environmentId, worldInstanceId, options = {}) {
         return this.owner('POST', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/ledger/replay`, options);
     }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@pouchy_ai/world-sdk",
-	"version": "0.8.0",
-	"description": "Server-side TypeScript client for Pouchy World — 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.",
+	"version": "0.9.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",
 	"homepage": "https://pouchy.ai/sdk",