@pouchy_ai/world-sdk 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @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.

package/README.md

@@ -78,6 +78,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 +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.10.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. */
@@ -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,6 +775,14 @@ 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.
      *

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.11.0';
 export const DEFAULT_BASE_URL = 'https://pouchy.ai/v1';
 // ── errors ─────────────────────────────────────────────────────────────────
 /** The refusal classes a world call can produce. `unknown` is deliberate: an
@@ -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,7 +525,11 @@ 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);

package/package.json

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