@pouchy_ai/world-sdk 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # @pouchy_ai/world-sdk
 
+## 0.10.0
+
+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
+  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
+  owner plane.
+- Why this exists: `adminToken` is a Firebase ID token — roughly an hour of life,
+  minted by a browser sign-in, with no API-key path. A backend could DRIVE a turn
+  with its own credentials (Secret Key + provider signature) and then needed a
+  human at a browser to find out what the turn did. Resuming after a crash was
+  the same story. That was the single thing keeping a sixty-minute integration
+  out of reach, and it was a credential gap, not a missing capability.
+- The mirror is reads only, and every route is GET. Driving a turn still needs
+  `secretKey` + `signing`: an admin key proves the PROJECT, never the Provider,
+  and the world's turn door requires both proofs. The delivery queue ACTIONS
+  (requeue, rehydrate, resolve-gap, drain), ledger archival, and the content loop
+  stay on `adminToken` — each decides something about a real reader's experience
+  of a story, or shortens the committed record.
+- Both doors answer from one shared server-side read, so which credential you
+  hold does not change the answer.
+- No existing method changed shape, and `adminToken` keeps working exactly as
+  before.
+
+## 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,50 @@ const world = new PouchyWorldClient({
 
 **Running** — `createWorldSession`, `runTurn`, `sendEvent`.
 
-**Reading** — `getWorldState`, `getTurn`, `replayLedger`, `replayLedgerToEnd`.
+**Reading** — `getWorldState`, `getTurn`, `listTurns`, `listTurnsSince`,
+`replayLedger`, `replayLedgerToEnd`.
+
+**Which credential does what.** This matters more than it looks: one of them
+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) | read the world: overview, state, timeline, turn read-back, metrics, delivery queue | drive a turn, act on the queue, author |
+| `adminToken` (Firebase ID token, ~1h) | everything above plus authoring and the content loop | outlive the hour |
+
+A server holds `secretKey` + `signing` + `adminKey` and needs no browser login
+anywhere in its deployment. `adminToken` is for a person, or for a script a
+person is watching.
+
+```ts
+const world = new PouchyWorldClient({
+  projectId: process.env.POUCHY_PROJECT_ID!,
+  secretKey: process.env.POUCHY_SECRET_KEY!,      // drive
+  adminKey:  process.env.POUCHY_ADMIN_KEY!,       // read back — does not expire
+  signing: { source: 'drama-backend', keyId: …, secret: … }
+});
+```
+
+An admin key proves the PROJECT, never the Provider, so it cannot drive a turn —
+the turn door requires a Secret Key *and* a signature over the exact bytes. And
+the delivery queue ACTIONS stay on `adminToken` on purpose: requeue, rehydrate
+and resolve-gap each decide what happens to a reader who is missing a beat, and
+resolve-gap tells them it is never coming.
+
+**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.10.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,
@@ -378,8 +474,23 @@ export interface WorldClientOptions {
     /** The project this client acts for. */
     projectId: string;
     /** An OWNER-plane credential (a signed-in admin's ID token) for the control
-     *  plane: story packages, world definitions, drafts, replay, reads. */
+     *  plane: story packages, world definitions, drafts, replay, reads.
+     *
+     *  Short-lived — a Firebase ID token, roughly an hour — and minted by a
+     *  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.
+     *
+     *  Long-lived and machine-held: this is what an unattended backend uses.
+     *  When present, the world READS (overview, state, timeline, turn read-back,
+     *  metrics, deliveries) go to the `/admin` mirror instead of the owner
+     *  plane, and no browser login is involved anywhere in your deployment.
+     *
+     *  It proves the PROJECT, never the Provider, so it cannot drive a turn —
+     *  that still needs `secretKey` + `signing`. Authoring calls and the content
+     *  loop still need `adminToken`; see the README for which is which. */
+    adminKey?: string;
     /** A project Secret Key (`pchy_sk_…`) for the MACHINE lane: world sessions,
      *  turns and trusted events. It also carries the test/live axis. */
     secretKey?: string;
@@ -401,6 +512,7 @@ export declare class PouchyWorldClient {
     private readonly baseUrl;
     private readonly doFetch;
     private readonly adminToken?;
+    private readonly adminKey?;
     private readonly secretKey?;
     private readonly signing?;
     private readonly timeoutMs;
@@ -448,10 +560,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;
@@ -623,6 +763,13 @@ export declare class PouchyWorldClient {
         schemaVersion?: number;
         occurredAt?: number;
     }): Promise<Record<string, unknown>>;
+    /** A world READ. Prefers the machine lane when an admin key is present.
+     *
+     *  `ownerPath` and `adminPath` address the same read through two doors; the
+     *  server answers both from one shared function, so which door you came in
+     *  by does not change the answer. The admin door drops `projectId` from the
+     *  path because the key already names the project. */
+    private read;
     private owner;
     /** The machine lane: Secret Key AND a source signature over the EXACT bytes
      *  being sent — the two proofs the world requires of a backend. */

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.10.0';
 export const DEFAULT_BASE_URL = 'https://pouchy.ai/v1';
 // ── errors ─────────────────────────────────────────────────────────────────
 /** The refusal classes a world call can produce. `unknown` is deliberate: an
@@ -222,6 +222,7 @@ export class PouchyWorldClient {
     baseUrl;
     doFetch;
     adminToken;
+    adminKey;
     secretKey;
     signing;
     timeoutMs;
@@ -233,6 +234,8 @@ export class PouchyWorldClient {
         this.doFetch = options.fetch ?? globalThis.fetch;
         if (options.adminToken !== undefined)
             this.adminToken = options.adminToken;
+        if (options.adminKey !== undefined)
+            this.adminKey = options.adminKey;
         if (options.secretKey !== undefined)
             this.secretKey = options.secretKey;
         if (options.signing !== undefined)
@@ -271,16 +274,67 @@ export class PouchyWorldClient {
         return this.owner('PATCH', `/projects/${this.projectId}/environments/${environmentId}`, definition);
     }
     getWorldState(environmentId, worldInstanceId) {
-        return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/state`);
+        return this.read(`/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/state`, `/admin/environments/${environmentId}/instances/${worldInstanceId}/state`);
     }
     /** 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)}`);
+        return this.read(`/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/turns/${encodeURIComponent(turnId)}`, `/admin/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.read(`/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/turns`, `/admin/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);
     }
@@ -304,7 +358,7 @@ export class PouchyWorldClient {
             if (v !== undefined)
                 q.set(k, String(v));
         const suffix = q.toString() ? `?${q}` : '';
-        return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/deliveries${suffix}`);
+        return this.read(`/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/deliveries`, `/admin/environments/${environmentId}/instances/${worldInstanceId}/deliveries`, suffix);
     }
     /** One delivery. `includePayload` returns the line itself and writes an audit
      *  row naming you — pass it deliberately, not by default. */
@@ -360,7 +414,7 @@ export class PouchyWorldClient {
      *  kept apart because "the lines arrived" and "the world played well" are
      *  different questions. */
     getWorldMetrics(environmentId, worldInstanceId) {
-        return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/metrics`);
+        return this.read(`/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/metrics`, `/admin/environments/${environmentId}/instances/${worldInstanceId}/metrics`);
     }
     /** Score the committed history against a quality suite. Deterministic — no
      *  model judges the output, so a score is something you can regress. */
@@ -476,9 +530,25 @@ export class PouchyWorldClient {
         return this.signed(`/projects/${this.projectId}/events`, body, eventId);
     }
     // ── transport ────────────────────────────────────────────────────────────
+    /** A world READ. Prefers the machine lane when an admin key is present.
+     *
+     *  `ownerPath` and `adminPath` address the same read through two doors; the
+     *  server answers both from one shared function, so which door you came in
+     *  by does not change the answer. The admin door drops `projectId` from the
+     *  path because the key already names the project. */
+    async read(ownerPath, adminPath, query = '') {
+        if (this.adminKey) {
+            return this.request('GET', `${adminPath}${query}`, {
+                headers: { authorization: `Bearer ${this.adminKey}` }
+            });
+        }
+        return this.owner('GET', `${ownerPath}${query}`);
+    }
     async owner(method, path, body) {
         if (!this.adminToken) {
-            throw new Error(`${method} ${path} needs an owner token (adminToken)`);
+            throw new Error(`${method} ${path} needs an owner token (adminToken) — or, for a world READ ` +
+                `from an unattended backend, a project admin key (adminKey), which routes ` +
+                `the read through the /admin mirror and does not expire`);
         }
         return this.request(method, path, {
             headers: { authorization: `Bearer ${this.adminToken}` },

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.10.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",