@pouchy_ai/world-sdk 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @pouchy_ai/world-sdk
 
+## 0.13.0
+
+- `createWorldSession` now returns a typed `WorldSessionResponse` instead of
+  `Record<string, unknown>`. The wire fields are unchanged — this names what the
+  server has always sent.
+- **The field is `session_token`, not `token`.** The untyped return let that
+  mistake compile: `conformance.mjs` asserted `session.token`, which the server
+  has never sent, so the session check threw against any real server while every
+  local gate stayed green. Typing the response is what stops it recurring; the
+  runner and both quickstarts were corrected to match.
+- `release-check.mjs` now compares `WORLD_SDK_VERSION` against the version of
+  the package it actually INSTALLED. The constant sat at `0.1.0` for eight
+  releases while the package shipped 0.8.0, so every request reported the wrong
+  client in its `user-agent`; the drift was corrected in 0.12.0, and this is the
+  gate that stops it recurring.
+- No method changed shape, and no request or response bytes changed.
+
 ## 0.12.0
 
 Additive: authoring joins the machine lane, so nothing in an integration needs
@@ -54,7 +71,7 @@ Additive: your backend can tell the world what it already knows. World API 1.8.
 
 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
+- New `adminKey` client option — a project admin key (`pchy_admin_…`), 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

package/README.md

@@ -56,7 +56,7 @@ 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) | 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 |
+| `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 |
 
 A server holds `secretKey` + `signing` + `adminKey` and needs **no browser login
@@ -157,16 +157,46 @@ an `approved` editorial can be exported.
 `newTurnId` / `isReservedTurnId` (idempotency), `describeTurn` (read a result
 without guessing), `WorldApiError` with typed codes and `.retryable`.
 
+## When a signed door refuses you
+
+All three signed doors answer one uniform 403 on a bad signature — they will
+never tell you which of the four things is wrong, because an endpoint that
+names the failing credential is an oracle. The reason lives in the project's own
+audit trail instead:
+
+```
+GET https://pouchy.ai/v1/projects/{projectId}/environments/{envId}/preflight
+Authorization: Bearer <OwnerToken>
+```
+
+**That is an OwnerToken — a signed-in project admin's Firebase ID token, not the
+Secret Key this client holds**, and not the Admin key either (preflight is
+deliberately absent from the `/admin` mirror). There is no SDK method for it for
+the same reason: it answers a question a developer asks once while looking at
+the dashboard, not one a backend asks in a loop.
+
+It returns the recent refusals with a closed reason vocabulary — `missing`,
+`malformed`, `unknown_key`, `stale`, `bad_signature`, `no_keys` — plus how many
+audit rows it scanned, because an empty feed is not a clean bill of health.
+
+`docs/world-sdk-errors.md` in the Pouchy repo maps every reason and every
+`WorldApiError` code to what to change.
+
 ## The three things integrators get wrong
 
 **1. Turn ids are the idempotency key.** Mint one per BEAT and re-send the same
 one to retry. A new id is a new beat: it will run the models again and commit
 again. `newTurnId()` exists so this is a deliberate choice rather than a habit.
 
-**2. Sign the bytes you send.** `signSourceRequest` hashes the exact body
-string. Serializing twice — once to sign, once to send — signs bytes you did
-not send, and the server will (correctly) refuse them. This client always signs
-the string it is about to write.
+**2. Sign the bytes you send, with the door's own id slot.** `signSourceRequest`
+hashes the exact body string. Serializing twice — once to sign, once to send —
+signs bytes you did not send, and the server will (correctly) refuse them. This
+client always signs the string it is about to write. The fourth canonical line
+is the ID SLOT, and it differs per door: `turnId` on the turns door, `eventId`
+on `/events`, and the body's own `world.request_id` on `/sessions` — a session
+mint has neither a turn nor an event. `createWorldSession` passes it for you; if you
+are signing by hand there, an invented or empty id verifies locally and comes
+back `bad_signature`, which reads exactly like a wrong secret.
 
 **3. Execution and delivery are different questions.** `executionStatus` says
 whether the world moved; `deliveryStatus` says whether the audience has heard

package/conformance.mjs

@@ -184,9 +184,12 @@ await check('session mint binds one user to one role (machine lane)', async () =
 		role: scenario.leadRole,
 		externalUserId: `conformance-${scenarioName}-${stamp}`
 	});
-	instanceId = session?.world?.instance ?? session?.world?.world_instance;
+	// The wire names, exactly as the server sends them (`WorldSessionResponse`).
+	// This check used to read `session.token`, which the server has never sent —
+	// so it threw against every real server while every local gate stayed green.
+	instanceId = session?.world?.instance;
 	if (!instanceId) throw new Error('no world instance in the session payload');
-	if (!session.token) throw new Error('no session token minted');
+	if (!session?.session_token) throw new Error('no session token minted (expected session_token)');
 	return instanceId;
 });
 

package/dist/index.d.ts

@@ -1,4 +1,10 @@
-export declare const WORLD_SDK_VERSION = "0.12.0";
+/** Kept in step with `package.json` by `release-check.mjs`, which compares this
+ *  constant against the version of the package it actually INSTALLED. It rides
+ *  the `user-agent` of every request, so a drift here misreports which client
+ *  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.13.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. */
@@ -26,7 +32,7 @@ export declare const SOURCE_SIGNATURE_HEADER = "X-Pouchy-Source-Signature";
 /** Build the `X-Pouchy-Source-Signature` header for one request body.
  *
  *  The canonical string is five newline-joined lines — scheme, unix seconds,
- *  the declared source, the event/turn id, and the sha256 of the EXACT body
+ *  the declared source, the door's id slot (see `id`), and the sha256 of the EXACT body
  *  bytes. Sign at SEND time, every attempt: a legitimate retry of the same id
  *  days later carries a fresh timestamp and passes the ±5 minute skew, because
  *  the signature proves origin and never doubles as a dedupe key.
@@ -36,7 +42,11 @@ export declare const SOURCE_SIGNATURE_HEADER = "X-Pouchy-Source-Signature";
  *  send. */
 export declare function signSourceRequest(input: {
     source: string;
-    /** eventId for `/events`, turnId for the turns door — the id slot. */
+    /** The id slot, which is per-door: `turnId` for the turns door, `eventId`
+     *  for `/events`, and the request's own `world.request_id` for `/sessions`
+     *  (`createWorldSession` passes it for you). A mint has neither a turn nor an
+     *  event, so signing an empty or invented id there is the classic first
+     *  failure — it verifies locally and is refused as `bad_signature`. */
     id: string;
     body: string;
     keyId: string;
@@ -470,6 +480,43 @@ export interface ApprovedScriptExportRow {
     deliveryAttempted?: number;
     deliveryOk?: number;
 }
+/** What `POST /v1/sessions` actually returns for a WORLD mint.
+ *
+ *  Typed because it was untyped: `createWorldSession` used to answer
+ *  `Record<string, unknown>`, so a caller reading `session.token` — a field the
+ *  server has never sent — compiled, shipped, and failed only against a live
+ *  server. The wire is snake_case and stays that way here; renaming it in the
+ *  client would put a second vocabulary between an integrator and the HTTP
+ *  responses they read in their own logs.
+ *
+ *  `world` is present because `createWorldSession` always sends a world block;
+ *  an ordinary (non-world) mint omits it, and that lane is not this method's. */
+export interface WorldSessionResponse {
+    /** The end-user session token. Hand it to YOUR frontend, which drives it with
+     *  `@pouchy_ai/companion-sdk`. Scoped to one instance and one role, and
+     *  carries no project credential. NOT named `token`. */
+    readonly session_token: string;
+    /** Seconds. The server clamps a requested ttl into [300, 86400]; this is the
+     *  clamped value, not what you asked for. */
+    readonly expires_in: number;
+    /** The agent the ROLE resolved to. The world decides it — passing an agent to
+     *  a world mint is refused. */
+    readonly agent: string;
+    readonly instance: {
+        readonly id: string;
+        readonly external_user_id: string;
+        /** True the first time this end user was provisioned. */
+        readonly created: boolean;
+    };
+    readonly world: {
+        readonly environment: string;
+        /** The revision this instance is PINNED to — for life. */
+        readonly environment_revision: number;
+        /** The world instance id to drive turns against. */
+        readonly instance: string;
+        readonly role: string;
+    };
+}
 export interface WorldClientOptions {
     /** The project this client acts for. */
     projectId: string;
@@ -480,7 +527,7 @@ export interface WorldClientOptions {
      *  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.
+    /** A project ADMIN key (`pchy_admin_…`), 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,
@@ -740,7 +787,7 @@ export declare class PouchyWorldClient {
         externalUserId: string;
         worldInstance?: string;
         requestId?: string;
-    }): Promise<Record<string, unknown>>;
+    }): Promise<WorldSessionResponse>;
     /** Drive ONE coordinated beat. `turnId` is the idempotency key: re-send the
      *  same one to retry, mint a new one for a new beat. */
     runTurn(input: {

package/dist/index.js

@@ -17,7 +17,13 @@
 // 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.12.0';
+/** Kept in step with `package.json` by `release-check.mjs`, which compares this
+ *  constant against the version of the package it actually INSTALLED. It rides
+ *  the `user-agent` of every request, so a drift here misreports which client
+ *  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.13.0';
 export const DEFAULT_BASE_URL = 'https://pouchy.ai/v1';
 // ── errors ─────────────────────────────────────────────────────────────────
 /** The refusal classes a world call can produce. `unknown` is deliberate: an
@@ -111,7 +117,7 @@ const SOURCE_SIGNATURE_SCHEME = 'POUCHY-SOURCE-V1';
 /** Build the `X-Pouchy-Source-Signature` header for one request body.
  *
  *  The canonical string is five newline-joined lines — scheme, unix seconds,
- *  the declared source, the event/turn id, and the sha256 of the EXACT body
+ *  the declared source, the door's id slot (see `id`), and the sha256 of the EXACT body
  *  bytes. Sign at SEND time, every attempt: a legitimate retry of the same id
  *  days later carries a fresh timestamp and passes the ±5 minute skew, because
  *  the signature proves origin and never doubles as a dedupe key.

package/package.json

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