@pouchy_ai/world-sdk 0.31.0 → 0.32.1

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # @pouchy_ai/world-sdk
 
+## 0.32.1
+
+- **Docs only — the eight `proposedPatches` ops are named.** No code change, no
+  type change, no method moves. `runTurn` and `sendEvent` have accepted
+  `proposedPatches` all along, and neither this package, its README, nor the
+  world OpenAPI ever said which ops the closed union holds.
+
+  An integrator reading this package's `index.d.ts` asked whether there was "an
+  entrance that does not depend on a model's judgement" — having searched the
+  live spec for `focusNodeId` and found nothing. The entrance was this field and
+  `complete_node` was the op they wanted. Publishing an example with one op in it
+  is not publishing a union.
+
+  The list is now in the README with each op's fields, in the field's own doc
+  comment (which is what reaches `index.d.ts`), and in the world OpenAPI as of
+  world API 1.39.0.
+
+## 0.32.0
+
+- **The content-return plane takes a project Secret Key.** Eight methods —
+  `listScriptDrafts`, `createScriptDraft`, `getScriptDraft`,
+  `exportScriptDraft`, `listEditorialDrafts`, `createEditorialDraft`,
+  `getEditorialDraft`, and `exportEditorialDraft({ preview: true })` — now send
+  `secretKey` when the client carries one, and fall back to `adminToken`
+  otherwise. World API 1.38.0.
+
+  The rule the server draws, and the reason it is not simply "open the plane":
+  **generate and read by machine, decide by human.** Every verb above DERIVES
+  material from beats already committed, and none of them writes a name that
+  later gates something. The ones that do are unchanged and still owner-only:
+  `reviewScriptDraft` (its `reviewedBy` is what the export gate reads),
+  `decideEditorialScene` (its verdicts are hashed into the approval digest),
+  `setEditorialStatus` (`approved` is what lets an export exist),
+  `exportEditorialDraft` WITHOUT `preview` (it stamps the draft exported), the
+  whole `approved-export` family, and the draft `DELETE` (which this client
+  does not expose at all) — that last one because it is a recursive delete
+  reaching approved exports through their parent, so the machine lane stops at a human signature in both directions:
+  it may not create one and it may not erase one.
+
+  No source signature here, unlike the turn and episode doors. Nothing on this
+  plane is AUTHORED — a draft is a projection of beats the provider already
+  signed for — so a second signature over the request would prove nothing that
+  the evidence does not already carry.
+
+  Asked for by an integrator whose nightly job generated drafts on a token
+  that expires in an hour, which meant a person had to be awake for a step
+  that reads a ledger. Additive: no method signature changed, and a client
+  configured only with `adminToken` behaves exactly as before.
+
 ## 0.31.0
 
 - **`WorldStateView`** — `getWorldState().state` is typed, instead of

package/README.md

@@ -28,6 +28,7 @@ credential. Drive that with `@pouchy_ai/companion-sdk`.
 |---|---|---|
 | owner | a signed-in project admin's ID token | author story packages and worlds; read state, turns, drafts; run replay |
 | machine | Secret Key **and** `X-Pouchy-Source-Signature` | mint sessions, drive turns, send trusted events |
+| keyed | Secret Key alone, no signature | generate and read script drafts and editorial readings (0.32.0) — nothing on that plane is authored, so there is nothing for a signature to prove |
 
 ```ts
 import { PouchyWorldClient, newTurnId, describeTurn } from '@pouchy_ai/world-sdk';
@@ -65,9 +66,9 @@ expires within the hour.
 
 | you hold | you can | you cannot |
 |---|---|---|
-| `secretKey` + `signing` | mint sessions, drive turns, send events | read anything back |
+| `secretKey` + `signing` | mint sessions, drive turns, send events; generate and read script drafts and editorial readings (0.32.0 — the signature is not used for those) | read the world back: state, timeline, metrics; decide anything in the content loop |
 | `adminKey` (`pchy_admin_…`, 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 |
+| `adminToken` (Firebase ID token, ~1h) | everything above plus the content loop's DECISIONS | outlive the hour |
 
 A server holds `secretKey` + `signing` + `adminKey` and needs **no browser login
 for the runtime loop**: author a story package and a world, mint sessions, drive
@@ -75,14 +76,35 @@ turns, and read everything back. `adminToken` is for a person, and the content
 loop's review step is a human decision — the point of it rather than an obstacle.
 
 **Which calls have no `/admin` mirror, and therefore need `adminToken`:** the
-whole content loop (`*ScriptDraft*`, `*EditorialDraft*`, `createApprovedExport`,
-`deriveStoryPackageCandidate`), the delivery-queue ACTIONS (`drainDeliveries`,
+content loop's DECISIONS (below), the delivery-queue ACTIONS (`drainDeliveries`,
 `requeueDelivery`, `rehydrateDelivery`, `resolveDeliveryGap`), `replayLedger`,
 `archiveLedger`, `evaluateWorld`, and `preflightWorld`. Reading an approved
 export back IS mirrored (`getApprovedExport`) — that is how a machine collects
 what a person approved, with the id arriving on the `world.script_approved`
 webhook.
 
+**The content loop splits at the signature (0.32.0 / world API 1.38.0):
+generate and read by machine, decide by human.** A project `secretKey` alone —
+no signature — now works on `listScriptDrafts`, `createScriptDraft`,
+`getScriptDraft`, `exportScriptDraft`, `listEditorialDrafts`,
+`createEditorialDraft`, `getEditorialDraft`, and
+`exportEditorialDraft({ preview: true })`. Every one of those DERIVES material
+from beats already committed, and none of them writes a name that later gates
+something. `adminToken` is still required for the ones that do:
+`reviewScriptDraft` (its reviewer is what the export gate reads),
+`decideEditorialScene` (its verdicts are hashed into the approval digest),
+`setEditorialStatus` (`approved` is what lets an export exist),
+`exportEditorialDraft` WITHOUT `preview` (it stamps the draft exported),
+`createApprovedExport` / `deriveStoryPackageCandidate`, and the draft `DELETE`
+(which this client does not expose at all) — that last one because it is a recursive delete reaching approved exports
+through their parent, so the machine lane stops at a human signature in both
+directions: it may not create one and it may not erase one.
+
+So an overnight job can run the whole derivation and a person still signs what
+leaves. The methods fall back to `adminToken` when no `secretKey` is
+configured, so a client that had only the owner token behaves exactly as
+before.
+
 `conformance.mjs` follows the same line: on an admin key alone it runs every
 runtime gate and SKIPS the two whose routes are owner-plane, printing why.
 Setting `POUCHY_ADMIN_TOKEN` as well runs all of them.
@@ -118,6 +140,30 @@ await world.runTurn({
 no single commit for a deterministic write to ride, and sending patches to one
 answers 422 rather than dropping them quietly.
 
+**The ops, in full.** A closed union of eight, published in the world OpenAPI
+from 1.39.0 and listed here because an integrator looking for "a way to move the
+story without depending on a model's judgement" had no way to find it:
+
+| op | fields | notes |
+|---|---|---|
+| `set_scene` | `sceneId` | must be a declared scene |
+| `advance_clock` | `by` | on top of the coordinator's own tick of 1 |
+| `set_location` | `location` | free text |
+| `set_flag` | `key`, `value` | the value must match the flag's declared `kind` |
+| `reveal_fact` | `factId` | must be a declared fact; append-only |
+| `complete_node` | `nodeId` | refused by name while a prerequisite is unmet |
+| `set_relation` | `between: [a, b]`, `descriptor` | symmetric; both must be declared roles |
+| `set_entity` | `entityId`, `descriptor` | |
+
+`note_private` exists in the union but is **not available to a provider** — it
+needs an acting role, and a provider batch has none.
+
+Ordered within the array, so a `complete_node` can satisfy a later op's
+prerequisite in the same call. All-or-nothing: one refused op commits nothing and
+the beat answers `rejected` with a per-op reason in `rejectedEffects`. At most 20
+ops. This is the PROVIDER acting as itself — it widens nothing a role may
+propose, and a role's own grant is untouched by it.
+
 **Focusing a beat on some of the cast.** By default every bound role answers a
 beat (up to the server cap). For an interview or a one-on-one scene, pass
 `focusRoles` and only those roles run — the rest are not billed and are

package/conformance.mjs

@@ -96,11 +96,12 @@ let failed = false;
 
 /** Marks a gate that CANNOT run on the credentials in hand.
  *
- *  Not a pass and not a failure. Two gates below drive the content loop and
- *  the ledger replay, and neither route has an `/admin` mirror — they are
- *  owner-plane by design ("creating stays human, reading does not"). Reporting
- *  them as FAIL would make a correctly-configured project look broken; leaving
- *  them out silently would make a partial run look complete. */
+ *  Not a pass and not a failure. ONE gate below — the ledger replay — has no
+ *  `/admin` mirror and no keyed lane; it is owner-plane by design. (The
+ *  content-loop gate was the second one until world API 1.38.0 gave its
+ *  derivation steps a Secret-Key lane; it now runs.) Reporting a skip as FAIL
+ *  would make a correctly-configured project look broken; leaving it out
+ *  silently would make a partial run look complete. */
 class NeedsOwnerToken extends Error {}
 
 async function check(name, fn) {
@@ -137,12 +138,18 @@ const world = new PouchyWorldClient({
 	// stopped requiring.
 	//
 	// CORRECTED: "either credential works" was too strong, and this file was the
-	// proof — two of its own gates call `replayLedgerToEnd` and
+	// proof — two of its own gates called `replayLedgerToEnd` and
 	// `createScriptDraft`, whose routes have NO `/admin` mirror. On an admin key
 	// alone they threw "needs an owner token", so the harness could not pass a
-	// correctly-configured project. Those two gates now SKIP with the reason
-	// printed; every runtime gate runs on the key. Set POUCHY_ADMIN_TOKEN as
-	// well to run all of them.
+	// correctly-configured project. Such gates SKIP with the reason printed;
+	// every runtime gate runs on the key. Set POUCHY_ADMIN_TOKEN as well to run
+	// all of them.
+	//
+	// NARROWED to ONE gate by world API 1.38.0 / SDK 0.32.0: the script-draft
+	// gate now rides the Secret Key this harness already holds, so `/ledger/replay`
+	// is the only remaining skip. The gate it skips is unchanged — the mirror
+	// question and the auth question are different questions, and replay still
+	// answers "no mirror".
 	...(process.env.POUCHY_ADMIN_KEY
 		? { adminKey: process.env.POUCHY_ADMIN_KEY }
 		: { adminToken: env('POUCHY_ADMIN_TOKEN') }),
@@ -276,8 +283,12 @@ await check('replay verifies the ledger against the served state', async () => {
 	return `consistent over ${report.entriesScanned} entr(ies)`;
 });
 
+// NO `requireOwnerToken` here since world API 1.38.0 / SDK 0.32.0: generating a
+// draft and reading it back are on the SECRET-KEY lane, which this harness
+// always holds, so the gate runs unattended. What stays owner-only is the
+// REVIEW — which is also why this gate can still prove the refusal below: the
+// export is meant to be refused until a person has read the draft.
 await check('a script draft generates and refuses export before review', async () => {
-	requireOwnerToken('/script-drafts');
 	const draft = await world.createScriptDraft(created.environmentId, instanceId);
 	if (draft.content?.humanReviewRequired !== true) {
 		throw new Error('draft did not carry humanReviewRequired');

package/dist/index.d.ts

@@ -4,7 +4,7 @@
  *  a project is running — which is exactly the field you reach for when a
  *  customer's integration behaves like an older SDK than they say they have.
  *  It sat at '0.1.0' for eight releases before anything compared the two. */
-export declare const WORLD_SDK_VERSION = "0.31.0";
+export declare const WORLD_SDK_VERSION = "0.32.1";
 export declare const DEFAULT_BASE_URL = "https://pouchy.ai/v1";
 /** One direction a beat could take. The WHOLE of what a deliberation shows a
  *  player: no reasoning, no role secrets, no simulated effects, no scores. */
@@ -1425,7 +1425,9 @@ export declare class PouchyWorldClient {
     createScriptDraft(environmentId: string, worldInstanceId: string): Promise<ScriptDraftRow>;
     getScriptDraft(environmentId: string, worldInstanceId: string, draftId: string): Promise<ScriptDraftRow>;
     /** Mark a draft reviewed. The reviewer is the SIGNED-IN human whose token
-     *  this client carries — never a field in the body. */
+     *  this client carries — never a field in the body, and never a Secret Key:
+     *  `reviewedBy` is what the export gate reads, so a machine that could write
+     *  it would be approving its own material. */
     reviewScriptDraft(environmentId: string, worldInstanceId: string, draftId: string, note?: string): Promise<ScriptDraftRow>;
     /** The reviewed draft as standard JSON. Refuses with 409 until a human has
      *  reviewed it — that gate is the product, not an obstacle. */
@@ -1495,7 +1497,18 @@ export declare class PouchyWorldClient {
          *  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. */
+         *  role's private notes.
+         *
+         *  The eight ops a provider may send, published in the world OpenAPI from
+         *  1.39.0 (see the README for each one's fields):
+         *
+         *    set_scene · advance_clock · set_location · set_flag · reveal_fact ·
+         *    complete_node · set_relation · set_entity
+         *
+         *  `complete_node` is the deterministic way to move plot progress, and
+         *  the array is ORDERED — one op may satisfy a later op's prerequisite.
+         *  At most 20 ops. `note_private` is in the union but refused to a
+         *  provider (it needs an acting role). */
         proposedPatches?: readonly Record<string, unknown>[];
     }): Promise<WorldTurnResult>;
     /** Ask for a few PUBLIC directions this beat could take, without taking it.
@@ -1566,6 +1579,24 @@ export declare class PouchyWorldClient {
     /** A world READ through whichever door the caller holds. */
     private read;
     private owner;
+    /** The SCRIPT-DRAFT lane (world API 1.38.0): a project Secret Key alone,
+     *  no source signature.
+     *
+     *  The rule the server draws here is **generate and read by machine, decide
+     *  by human**. Every verb on this lane DERIVES material from beats already
+     *  committed — a draft, an editorial reading, a JSON read-back — and none of
+     *  them writes a name that later gates something: the reviewer, the scene
+     *  decisions hashed into the approval digest, and the approved export all
+     *  stay on the owner token. So a backend can run the whole derivation
+     *  overnight and a person still signs what leaves.
+     *
+     *  No signature, unlike `signed`, because nothing on this lane is AUTHORED:
+     *  a draft is a projection of beats the provider already signed for, so a
+     *  second signature over the request would prove nothing new.
+     *
+     *  Falls back to the owner token when no Secret Key is configured, so a
+     *  client that only ever had `adminToken` keeps working unchanged. */
+    private keyed;
     /** The machine lane: Secret Key AND a source signature over the EXACT bytes
      *  being sent — the two proofs the world requires of a backend. */
     private signed;

package/dist/index.js

@@ -23,7 +23,7 @@ import { createHash, createHmac, randomUUID } from 'node:crypto';
  *  a project is running — which is exactly the field you reach for when a
  *  customer's integration behaves like an older SDK than they say they have.
  *  It sat at '0.1.0' for eight releases before anything compared the two. */
-export const WORLD_SDK_VERSION = '0.31.0';
+export const WORLD_SDK_VERSION = '0.32.1';
 export const DEFAULT_BASE_URL = 'https://pouchy.ai/v1';
 /** Read the commit turn id out of an envelope, so the signature covers the id
  *  the server will commit under. The payload half is base64url JSON; the
@@ -732,40 +732,57 @@ export class PouchyWorldClient {
     archiveLedger(environmentId, worldInstanceId, options = {}) {
         return this.owner('POST', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/ledger/archive`, { action: options.action ?? 'plan', ...(options.confirm ? { confirm: true } : {}) });
     }
+    // ── the content-return plane ─────────────────────────────────────────────
+    //
+    // TWO LANES since world API 1.38.0: a project **Secret Key** works on every
+    // verb that DERIVES material — list/generate/read a draft, list/generate/read
+    // an editorial reading, read either one back as JSON, preview an export —
+    // and the OWNER TOKEN is still required for every verb that DECIDES:
+    // `reviewScriptDraft` (its reviewer gates the export), `decideEditorialScene`
+    // (its verdicts are hashed into the approval digest), `setEditorialStatus`
+    // (`approved` is what lets an export exist), `exportEditorialDraft` without
+    // `preview` (it stamps the draft exported), the whole `approved-export`
+    // family, and the draft DELETE — which this client does not expose at all —
+    // because it reaches approved exports through their parent). Generate and read by machine, decide by human.
+    //
+    // The derivation methods fall back to `adminToken` when no `secretKey` is
+    // configured, so nothing that worked before needs changing.
     listScriptDrafts(environmentId, worldInstanceId) {
-        return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts`);
+        return this.keyed('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts`);
     }
     /** Generate (or return) the draft for this instance's committed history.
      *  Idempotent on the ledger range: the same range is the same draft. */
     createScriptDraft(environmentId, worldInstanceId) {
-        return this.owner('POST', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts`, {});
+        return this.keyed('POST', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts`, {});
     }
     getScriptDraft(environmentId, worldInstanceId, draftId) {
-        return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}`);
+        return this.keyed('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}`);
     }
     /** Mark a draft reviewed. The reviewer is the SIGNED-IN human whose token
-     *  this client carries — never a field in the body. */
+     *  this client carries — never a field in the body, and never a Secret Key:
+     *  `reviewedBy` is what the export gate reads, so a machine that could write
+     *  it would be approving its own material. */
     reviewScriptDraft(environmentId, worldInstanceId, draftId, note) {
         return this.owner('POST', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/review`, note ? { note } : {});
     }
     /** The reviewed draft as standard JSON. Refuses with 409 until a human has
      *  reviewed it — that gate is the product, not an obstacle. */
     exportScriptDraft(environmentId, worldInstanceId, draftId) {
-        return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/export`);
+        return this.keyed('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/export`);
     }
     /** The EDITORIAL layer over an evidence draft (Batch 6). The evidence draft
      *  is deterministic and never changes; this is a model's reading of it, and
      *  every line it claims came from the story was re-checked server-side. */
     listEditorialDrafts(environmentId, worldInstanceId, draftId) {
-        return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/editorial`);
+        return this.keyed('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/editorial`);
     }
     /** Generate (or return) an editorial reading. Idempotent per model + prompt
      *  version + input digest, so asking twice is not a second opinion. */
     createEditorialDraft(environmentId, worldInstanceId, draftId, model) {
-        return this.owner('POST', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/editorial`, model ? { model } : {});
+        return this.keyed('POST', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/editorial`, model ? { model } : {});
     }
     getEditorialDraft(environmentId, worldInstanceId, draftId, editorialId) {
-        return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/editorial/${editorialId}`);
+        return this.keyed('GET', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/editorial/${editorialId}`);
     }
     /** Move an editorial draft through its review lifecycle. `exported` is not
      *  settable here — `exportEditorialDraft` writes it. */
@@ -781,7 +798,9 @@ export class PouchyWorldClient {
      *  without stamping it exported, so a reviewer can see what would leave. */
     exportEditorialDraft(environmentId, worldInstanceId, draftId, editorialId, options = {}) {
         const path = `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/script-drafts/${draftId}/editorial/${editorialId}/export`;
-        return options.preview ? this.owner('GET', path) : this.owner('POST', path, {});
+        // The PREVIEW read is on the two-lane door; the export itself STAMPS the
+        // draft exported and stays owner-only.
+        return options.preview ? this.keyed('GET', path) : this.owner('POST', path, {});
     }
     // ── machine lane (secret key + source signature) ─────────────────────────
     /** Mint a world SESSION for one end user in one role. The returned token is
@@ -912,6 +931,32 @@ export class PouchyWorldClient {
             ...(body !== undefined ? { raw: JSON.stringify(body) } : {})
         });
     }
+    /** The SCRIPT-DRAFT lane (world API 1.38.0): a project Secret Key alone,
+     *  no source signature.
+     *
+     *  The rule the server draws here is **generate and read by machine, decide
+     *  by human**. Every verb on this lane DERIVES material from beats already
+     *  committed — a draft, an editorial reading, a JSON read-back — and none of
+     *  them writes a name that later gates something: the reviewer, the scene
+     *  decisions hashed into the approval digest, and the approved export all
+     *  stay on the owner token. So a backend can run the whole derivation
+     *  overnight and a person still signs what leaves.
+     *
+     *  No signature, unlike `signed`, because nothing on this lane is AUTHORED:
+     *  a draft is a projection of beats the provider already signed for, so a
+     *  second signature over the request would prove nothing new.
+     *
+     *  Falls back to the owner token when no Secret Key is configured, so a
+     *  client that only ever had `adminToken` keeps working unchanged. */
+    async keyed(method, path, body) {
+        if (this.secretKey) {
+            return this.request(method, path, {
+                headers: { authorization: `Bearer ${this.secretKey}` },
+                ...(body !== undefined ? { raw: JSON.stringify(body) } : {})
+            });
+        }
+        return this.owner(method, path, body);
+    }
     /** The machine lane: Secret Key AND a source signature over the EXACT bytes
      *  being sent — the two proofs the world requires of a backend. */
     async signed(path, body, idSlot) {

package/package.json

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