@pouchy_ai/world-sdk 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # @pouchy_ai/world-sdk
 
+## 0.11.0
+
+Additive: your backend can tell the world what it already knows. World API 1.8.
+
+- `runTurn` and `sendEvent` both accept `proposedPatches` — PROVIDER-authored
+  state changes committed with the beat. The server has accepted them on the
+  turns door since Batch 5; the SDK never exposed the field, and the event lane
+  never carried one at all. So a fact your system holds ("the payment cleared",
+  "the shipment arrived", "the player really does have the key") could only WAKE
+  the characters and hope one of them proposed the right effect.
+- They ride the coordinator's single commit alongside the roles' settled
+  effects, and are validated server-side against the closed StatePatch union and
+  the pinned story package — all-or-nothing, so a batch with one bad op commits
+  nothing. A provider cannot write a role's private notes.
+- COORDINATED worlds only. An actor world wakes each role separately and has no
+  single commit for a deterministic write to ride, so sending patches to one is
+  **refused with 422** rather than silently dropped. That refusal is the feature:
+  a channel that accepts input and discards it is the failure mode this project
+  has recorded three times, and it always reads as success.
+- `agent.event_reply` webhooks from a coordinated world now carry `turnId`,
+  `stateRevision` and `sequence` in the `world` block. Until now a consumer got
+  the instance and the role and nothing else — it could not join the reply back
+  to the ledger turn, could not tell whether the world had moved, and could not
+  order two lines of one beat, since webhook delivery is per-message and
+  promises no ordering. All three are additive.
+- No existing method changed shape.
+
+## 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

package/README.md

@@ -50,6 +50,50 @@ const world = new PouchyWorldClient({
 **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.
+
+**Telling the world a fact you already hold.** Your system knows things the
+model can only guess at. Send them as patches and the world records them,
+instead of hoping a character proposes the right effect:
+
+```ts
+await world.runTurn({
+  environmentId, worldInstanceId,
+  text: 'I hand over the coin pouch.',
+  proposedPatches: [{ op: 'set_flag', key: 'paid', value: true }]
+});
+```
+
+`sendEvent` takes the same field. Coordinated worlds only — an actor world has
+no single commit for a deterministic write to ride, and sending patches to one
+answers 422 rather than dropping them quietly.
+
 **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
@@ -150,6 +194,8 @@ and exits non-zero on the first structural failure.
 
 - `docs/world-quickstart-drama.md` — screenplay → world → new screenplay draft
 - `docs/world-quickstart-npc.md` — one town, three NPCs, one shared state
+- `docs/world-quickstart-nextjs.md` — a Next.js app: one route handler, one page,
+  no browser login anywhere in the deployment
 
 ## License
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const WORLD_SDK_VERSION = "0.9.0";
+export declare const WORLD_SDK_VERSION = "0.11.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. */
@@ -474,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;
@@ -497,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;
@@ -734,6 +750,19 @@ export declare class PouchyWorldClient {
         text: string;
         sourceRoleId?: string;
         traceId?: string;
+        /** PROVIDER-authored state changes, committed with this beat.
+         *
+         *  Your backend already knows things the model can only guess at — the
+         *  payment cleared, the shipment arrived, the player actually holds the
+         *  key. Send them as patches and the world HOLDS them, rather than
+         *  hoping a character proposes the right effect.
+         *
+         *  They ride the coordinator's single commit alongside the roles'
+         *  settled effects, and are validated server-side against the closed
+         *  StatePatch union and the pinned story package — all-or-nothing, so a
+         *  batch with one bad op commits nothing. A provider cannot write a
+         *  role's private notes. */
+        proposedPatches?: readonly Record<string, unknown>[];
     }): 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.
@@ -746,7 +775,22 @@ export declare class PouchyWorldClient {
         data: Record<string, unknown>;
         schemaVersion?: number;
         occurredAt?: number;
+        /** PROVIDER-authored state changes to commit with the beat this event
+         *  produces. Same contract as `runTurn`'s.
+         *
+         *  COORDINATED worlds only. An actor world wakes each role separately
+         *  and has no single commit for a deterministic write to ride, so
+         *  sending these to one is refused with 422 rather than silently
+         *  dropped — you will hear about it, which is the point. */
+        proposedPatches?: readonly Record<string, unknown>[];
     }): 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.9.0';
+export const WORLD_SDK_VERSION = '0.11.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,7 +274,7 @@ 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. */
@@ -282,7 +285,7 @@ export class PouchyWorldClient {
      *  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
@@ -300,7 +303,7 @@ export class PouchyWorldClient {
         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}`);
+        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
@@ -355,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. */
@@ -411,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. */
@@ -505,7 +508,8 @@ export class PouchyWorldClient {
             trigger: {
                 kind: 'user',
                 text: input.text,
-                ...(input.sourceRoleId ? { sourceRoleId: input.sourceRoleId } : {})
+                ...(input.sourceRoleId ? { sourceRoleId: input.sourceRoleId } : {}),
+                ...(input.proposedPatches ? { proposedPatches: input.proposedPatches } : {})
             },
             ...(input.traceId ? { traceId: input.traceId } : {})
         };
@@ -521,15 +525,35 @@ export class PouchyWorldClient {
             eventId,
             schemaVersion: input.schemaVersion ?? 1,
             data: input.data,
-            world: { environment: input.environment, instance: input.worldInstance },
+            world: {
+                environment: input.environment,
+                instance: input.worldInstance,
+                ...(input.proposedPatches ? { proposedPatches: input.proposedPatches } : {})
+            },
             ...(input.occurredAt !== undefined ? { occurredAt: input.occurredAt } : {})
         };
         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,6 +1,6 @@
 {
 	"name": "@pouchy_ai/world-sdk",
-	"version": "0.9.0",
+	"version": "0.11.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",