@pouchy_ai/world-sdk 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @pouchy_ai/world-sdk
 
+## 0.12.0
+
+Additive: authoring joins the machine lane, so nothing in an integration needs
+a browser.
+
+- `createStoryPackage`, `publishStoryPackage`, `getStoryPackage`,
+  `listStoryPackages`, `createWorld`, `publishWorld`, `getWorld` and
+  `listWorlds` now go to the `/v1/admin` plane when `adminKey` is set, exactly
+  as the reads have since 0.10.0.
+- These admin equivalents have existed since Batch 1. The SDK simply never used
+  them, so authoring kept demanding `adminToken` — a Firebase ID token, minted
+  by a browser sign-in and good for about an hour — for operations a project
+  admin key could always perform.
+- **`conformance.mjs` runs on machine credentials now.** That is what this
+  release is for. The one check that proves a project's world plane is wired
+  correctly could not run without a person opening a browser first, which is
+  precisely what the rest of this SDK stopped requiring in 0.10.0. Set
+  `POUCHY_ADMIN_KEY`; `POUCHY_ADMIN_TOKEN` still works if you prefer it.
+- `adminToken` remains supported and unchanged. It is still the only credential
+  for the content loop (script drafts, editorial review), where a person is the
+  point rather than an obstacle.
+- No method changed shape.
+
+## 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.

package/README.md

@@ -56,12 +56,13 @@ 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 |
+| `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 |
+| `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
-anywhere in its deployment. `adminToken` is for a person, or for a script a
-person is watching.
+A server holds `secretKey` + `signing` + `adminKey` and needs **no browser login
+anywhere in its deployment** — including `conformance.mjs`, which used to demand
+one. `adminToken` is for a person: the content loop's review step is a human
+decision, which is the point of it rather than an obstacle.
 
 ```ts
 const world = new PouchyWorldClient({
@@ -78,6 +79,22 @@ 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
@@ -178,6 +195,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/conformance.mjs

@@ -20,7 +20,7 @@
 // has to answer AND touch world state, which is the failure mode that matters
 // there (an NPC that chats without the world moving looks fine and is not).
 //
-//   POUCHY_PROJECT_ID=… POUCHY_ADMIN_TOKEN=… POUCHY_SECRET_KEY=… \
+//   POUCHY_PROJECT_ID=… POUCHY_ADMIN_KEY=… POUCHY_SECRET_KEY=… \
 //   POUCHY_SOURCE=… POUCHY_SOURCE_KID=… POUCHY_SOURCE_SECRET=… \
 //   POUCHY_AGENT_A=… POUCHY_AGENT_B=… node conformance.mjs [--scenario=drama|npc]
 
@@ -114,7 +114,17 @@ async function check(name, fn) {
 
 const world = new PouchyWorldClient({
 	projectId: env('POUCHY_PROJECT_ID'),
-	adminToken: env('POUCHY_ADMIN_TOKEN'),
+	// Batch 10: an ADMIN KEY is enough, and is the point.
+	//
+	// This harness used to demand POUCHY_ADMIN_TOKEN — a Firebase ID token,
+	// browser-minted and good for about an hour. So the one check that proves a
+	// project's world plane is wired correctly could not run without a person
+	// opening a browser first, which is exactly the thing the rest of this SDK
+	// stopped requiring. Either credential works now; the key is preferred and
+	// needs no human.
+	...(process.env.POUCHY_ADMIN_KEY
+		? { adminKey: process.env.POUCHY_ADMIN_KEY }
+		: { adminToken: env('POUCHY_ADMIN_TOKEN') }),
 	secretKey: env('POUCHY_SECRET_KEY'),
 	signing: {
 		source: env('POUCHY_SOURCE'),

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const WORLD_SDK_VERSION = "0.10.0";
+export declare const WORLD_SDK_VERSION = "0.12.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. */
@@ -750,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.
@@ -762,13 +775,32 @@ 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.
+    /** A call that BOTH planes serve. 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. */
+     *  `ownerPath` and `adminPath` address the same operation through two doors,
+     *  and the server answers both from one shared implementation — 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,
+     *  which is also what makes it unable to address another project's work.
+     *
+     *  Batch 10 PR-B2.1 widened this from reads to AUTHORING. The admin
+     *  equivalents for story packages and world definitions have existed since
+     *  Batch 1; the SDK simply never used them, which left `createStoryPackage`
+     *  and friends demanding an hour-lived browser token for an operation a
+     *  machine key could always perform. `conformance.mjs` is the proof: it
+     *  could not run without a person opening a browser first. */
+    private machine;
+    /** A world READ through whichever door the caller holds. */
     private read;
     private owner;
     /** The machine lane: Secret Key AND a source signature over the EXACT bytes

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.10.0';
+export const WORLD_SDK_VERSION = '0.12.0';
 export const DEFAULT_BASE_URL = 'https://pouchy.ai/v1';
 // ── errors ─────────────────────────────────────────────────────────────────
 /** The refusal classes a world call can produce. `unknown` is deliberate: an
@@ -244,34 +244,34 @@ export class PouchyWorldClient {
     }
     // ── control plane (owner token) ──────────────────────────────────────────
     listStoryPackages() {
-        return this.owner('GET', `/projects/${this.projectId}/story-packages`);
+        return this.machine('GET', `/projects/${this.projectId}/story-packages`, '/admin/story-packages');
     }
     createStoryPackage(content) {
-        return this.owner('POST', `/projects/${this.projectId}/story-packages`, content);
+        return this.machine('POST', `/projects/${this.projectId}/story-packages`, '/admin/story-packages', content);
     }
     getStoryPackage(packageId) {
-        return this.owner('GET', `/projects/${this.projectId}/story-packages/${packageId}`);
+        return this.machine('GET', `/projects/${this.projectId}/story-packages/${packageId}`, `/admin/story-packages/${packageId}`);
     }
     /** Publish the next IMMUTABLE story revision. Idempotent on content: the
      *  same bytes return the existing revision rather than minting a twin. */
     publishStoryPackage(packageId, content) {
-        return this.owner('PATCH', `/projects/${this.projectId}/story-packages/${packageId}`, content);
+        return this.machine('PATCH', `/projects/${this.projectId}/story-packages/${packageId}`, `/admin/story-packages/${packageId}`, content);
     }
     listWorlds() {
-        return this.owner('GET', `/projects/${this.projectId}/environments`);
+        return this.machine('GET', `/projects/${this.projectId}/environments`, '/admin/environments');
     }
     createWorld(definition) {
-        return this.owner('POST', `/projects/${this.projectId}/environments`, definition);
+        return this.machine('POST', `/projects/${this.projectId}/environments`, '/admin/environments', definition);
     }
     getWorld(environmentId) {
-        return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}`);
+        return this.machine('GET', `/projects/${this.projectId}/environments/${environmentId}`, `/admin/environments/${environmentId}`);
     }
     /** Publish the next world revision. Existing world INSTANCES keep the
      *  revision they were created on — a published change reaches new instances
      *  only, which is what keeps a running story from changing runtime or rules
      *  underneath its players. */
     publishWorld(environmentId, definition) {
-        return this.owner('PATCH', `/projects/${this.projectId}/environments/${environmentId}`, definition);
+        return this.machine('PATCH', `/projects/${this.projectId}/environments/${environmentId}`, `/admin/environments/${environmentId}`, definition);
     }
     getWorldState(environmentId, worldInstanceId) {
         return this.read(`/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/state`, `/admin/environments/${environmentId}/instances/${worldInstanceId}/state`);
@@ -508,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 } : {})
         };
@@ -524,25 +525,43 @@ 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.
+    /** A call that BOTH planes serve. 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 = '') {
+     *  `ownerPath` and `adminPath` address the same operation through two doors,
+     *  and the server answers both from one shared implementation — 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,
+     *  which is also what makes it unable to address another project's work.
+     *
+     *  Batch 10 PR-B2.1 widened this from reads to AUTHORING. The admin
+     *  equivalents for story packages and world definitions have existed since
+     *  Batch 1; the SDK simply never used them, which left `createStoryPackage`
+     *  and friends demanding an hour-lived browser token for an operation a
+     *  machine key could always perform. `conformance.mjs` is the proof: it
+     *  could not run without a person opening a browser first. */
+    async machine(method, ownerPath, adminPath, body, query = '') {
         if (this.adminKey) {
-            return this.request('GET', `${adminPath}${query}`, {
-                headers: { authorization: `Bearer ${this.adminKey}` }
+            return this.request(method, `${adminPath}${query}`, {
+                headers: { authorization: `Bearer ${this.adminKey}` },
+                ...(body !== undefined ? { raw: JSON.stringify(body) } : {})
             });
         }
-        return this.owner('GET', `${ownerPath}${query}`);
+        return this.owner(method, `${ownerPath}${query}`, body);
+    }
+    /** A world READ through whichever door the caller holds. */
+    async read(ownerPath, adminPath, query = '') {
+        return this.machine('GET', ownerPath, adminPath, undefined, query);
     }
     async owner(method, path, body) {
         if (!this.adminToken) {

package/package.json

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