@pouchy_ai/world-sdk 0.19.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # @pouchy_ai/world-sdk
 
+## 0.22.0
+
+- **`startNextEpisode(environmentId, worldInstanceId)`** — start the next
+  episode of a worldline that just finished one, and receive the CARRYOVER.
+- The worldline does **not** restart. Its `worldInstanceId`, membership, state
+  and ledger all continue; the episode moves on. Nothing is copied and nothing
+  is deleted, so there is no migration to get wrong.
+- **Idempotent.** The run id is derived from the worldline, the episode and the
+  revision it starts at, so a retry lands on the same run and answers
+  `created: false` rather than forking the story.
+- **Owner token only** — no `/admin` mirror, same reasoning as `preflightWorld`:
+  the mirror carries reads, and this is the write that decides a story moves on.
+- New types: `WorldCarryoverV1`, `WorldNextEpisodeResponse`. The carryover is a
+  **projection** of facts the worldline already holds — canon it established,
+  where the characters stand, threads left hanging, setups never paid off.
+  Role-private notes are never in it, and no memory is carried because the world
+  runtime writes none.
+- Server-side this is world API 1.28.0.
+
+## 0.21.0
+
+- **`WorldProgressCheckpointV1.episode`** — which episode a serial worldline is
+  playing, its beats-spent and turn budget, and the ending once it has one.
+  Absent for every world whose pinned story is not a serial, which is most of
+  them, so nothing an existing integration reads has changed shape.
+- **Type-only.** No new method, no new route: `getProgress` already returned
+  this checkpoint and now returns one more optional field.
+- `beatsCommitted` and `turnBudget` are two numbers, **not a ratio** — the same
+  rule as `completedNodeCount` / `declaredNodeCount`. A budget is the ceiling at
+  which the author's fallback ending fires, not a denominator of progress.
+- `endingId` is decided **server-side** from committed state and the package's
+  declared rules. No client, prompt or model supplies it.
+- Server-side this is world API 1.26.0 — Story Contract v3 (`series`). Publishing
+  a v3 package needs `POUCHY_STORY_CONTRACT_V3_WRITE` on the deployment; until
+  then such a publish is refused with `code: "story_contract_v3_write_disabled"`.
+
+## 0.20.0
+
+- **Seven methods for routes that already existed.** `getWorldOverview`,
+  `getWorldCost`, `listWorldVersions`, `listStoryPackageVersions`,
+  `setWorldDisabled`, `setStoryPackageDisabled` (all `adminKey`-capable), and
+  `preflightWorld` (owner plane only — no `/admin` mirror).
+- **Two of them the README already promised.** Its credential table listed
+  `overview` and `cost` as `adminKey` reads, and there was no method to make
+  them with. `getWorldOverview` is the one to reach for first: it carries
+  `ready` and the `blockers` behind a false, and unlike `preflightWorld` a
+  machine can call it.
+- **`conformance.mjs` no longer fails a correctly-configured project.** Its
+  header claimed an admin key was enough; two of its own gates call
+  `replayLedgerToEnd` and `createScriptDraft`, whose routes have no `/admin`
+  mirror, so on a key alone they threw "needs an owner token". Those gates now
+  SKIP with the reason printed, and skips are counted apart from passes rather
+  than folded into the ratio.
+- No API change — `WORLD_API_VERSION` stays at 1.24.0. Every route these
+  methods call has been served on both planes since Batch 1; only the client
+  was missing.
+
 ## 0.19.0
 
 - `getApprovedExport(environmentId, worldInstanceId, draftId, editorialId, exportId)`

package/README.md

@@ -52,7 +52,10 @@ directions a beat could take, then commit the one the player picked. Off unless
 the world's published revision declares it; the `envelope` is server-side only.
 
 **Reading** — `getWorldState`, `getProgress`, `getTurn`, `listTurns`,
-`listTurnsSince`, `replayLedger`, `replayLedgerToEnd`, `scanConsistency`.
+`listTurnsSince`, `replayLedger`, `replayLedgerToEnd`, `scanConsistency`,
+`getWorldOverview`, `getWorldCost`, `listWorldVersions`,
+`listStoryPackageVersions`, `setWorldDisabled`, `setStoryPackageDisabled`,
+`preflightWorld`.
 
 **Which credential does what.** This matters more than it looks: one of them
 expires within the hour.
@@ -64,9 +67,22 @@ expires within the hour.
 | `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** — 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.
+for the runtime loop**: author a story package and a world, mint sessions, drive
+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`,
+`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.
+
+`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.
 
 ```ts
 const world = new PouchyWorldClient({

package/conformance.mjs

@@ -94,12 +94,26 @@ console.log(`Pouchy World conformance — ${scenario.label} scenario\n`);
 const results = [];
 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. */
+class NeedsOwnerToken extends Error {}
+
 async function check(name, fn) {
 	try {
 		const detail = await fn();
 		results.push({ name, ok: true, detail });
 		console.log(`PASS  ${name}${detail ? ` — ${detail}` : ''}`);
 	} catch (err) {
+		if (err instanceof NeedsOwnerToken) {
+			results.push({ name, ok: null, detail: err.message });
+			console.log(`SKIP  ${name} — ${err.message}`);
+			return;
+		}
 		failed = true;
 		const detail =
 			err instanceof WorldApiError
@@ -114,14 +128,21 @@ async function check(name, fn) {
 
 const world = new PouchyWorldClient({
 	projectId: env('POUCHY_PROJECT_ID'),
-	// Batch 10: an ADMIN KEY is enough, and is the point.
+	// Batch 10: an ADMIN KEY carries the RUNTIME loop, which 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.
+	// stopped requiring.
+	//
+	// CORRECTED: "either credential works" was too strong, and this file was the
+	// proof — two of its own gates call `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.
 	...(process.env.POUCHY_ADMIN_KEY
 		? { adminKey: process.env.POUCHY_ADMIN_KEY }
 		: { adminToken: env('POUCHY_ADMIN_TOKEN') }),
@@ -133,6 +154,15 @@ const world = new PouchyWorldClient({
 	},
 	...(process.env.POUCHY_BASE_URL ? { baseUrl: process.env.POUCHY_BASE_URL } : {})
 });
+/** Throws a SKIP for a gate whose route is owner-plane only. */
+function requireOwnerToken(route) {
+	if (!process.env.POUCHY_ADMIN_TOKEN) {
+		throw new NeedsOwnerToken(
+			`${route} has no /admin mirror — set POUCHY_ADMIN_TOKEN to run this gate`
+		);
+	}
+}
+
 const agentA = env('POUCHY_AGENT_A');
 const agentB = env('POUCHY_AGENT_B');
 const stamp = Date.now().toString(36);
@@ -237,6 +267,7 @@ await check('world state reads back (user projection, no private layer)', async
 });
 
 await check('replay verifies the ledger against the served state', async () => {
+	requireOwnerToken('/ledger/replay');
 	const report = await world.replayLedgerToEnd(created.environmentId, instanceId);
 	if (report.verdict !== 'consistent') {
 		throw new Error(`${report.verdict}${report.detail ? `: ${report.detail}` : ''}`);
@@ -246,6 +277,7 @@ await check('replay verifies the ledger against the served state', async () => {
 });
 
 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');
@@ -284,9 +316,24 @@ await check('a WRONG signature is refused (the second proof is real)', async ()
 });
 
 console.log('');
-console.log(`${results.filter((r) => r.ok).length}/${results.length} checks passed`);
+// SKIPPED is counted apart from PASSED, never folded into a ratio. A gate that
+// could not run is not a gate that passed, and "8/10 passed" would read as two
+// failures — the opposite of what happened.
+const passed = results.filter((r) => r.ok === true).length;
+const skipped = results.filter((r) => r.ok === null).length;
+const ran = results.length - skipped;
+console.log(
+	`${passed}/${ran} checks passed` + (skipped ? ` · ${skipped} skipped (no owner token)` : '')
+);
 if (failed) {
 	console.error('Conformance FAILED — fix the first failure above before writing product code.');
 	process.exit(1);
 }
-console.log('Conformance passed. The world plane is wired correctly for this project.');
+if (skipped) {
+	console.log(
+		`The RUNTIME plane is wired correctly. ${skipped} content-loop gate(s) did not run: ` +
+			`their routes are owner-plane only. Set POUCHY_ADMIN_TOKEN to cover them too.`
+	);
+} else {
+	console.log('Conformance passed. The world plane is wired correctly for this project.');
+}

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.19.0";
+export declare const WORLD_SDK_VERSION = "0.22.0";
 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. */
@@ -216,8 +216,81 @@ export interface WorldProgressCheckpointV1 {
         branchId: string;
         condition: string;
     }>;
+    /** The episode this worldline is playing, when its pinned story is a
+     *  serial. ABSENT for every non-serial world, which is most of them.
+     *
+     *  `beatsCommitted` and `turnBudget` are two numbers, not a ratio — same
+     *  rule as `completedNodeCount` / `declaredNodeCount`. A budget is the
+     *  ceiling at which the author's fallback ending fires, not a denominator
+     *  of progress.
+     *
+     *  `endingId` appears only once the episode is over. It is decided
+     *  server-side from committed state and the package's declared rules; no
+     *  client, prompt or model supplies it. */
+    episode?: {
+        seriesId: string;
+        episodeId: string;
+        title: string;
+        status: 'active' | 'ended';
+        beatsCommitted: number;
+        turnBudget: number;
+        endingId?: string;
+        endingTitle?: string;
+    };
     rebuildable: true;
 }
+/** What the next episode gets to stand on. A PROJECTION of facts the worldline
+ *  already holds, not a copy of them — nothing is moved and nothing is deleted.
+ *
+ *  Role-private notes are never here. Neither is memory: the world runtime
+ *  writes none, so there is nothing to inherit. */
+export interface WorldCarryoverV1 {
+    contractVersion: 1;
+    fromEpisodeId: string;
+    fromEndingId: string;
+    toEpisodeId: string;
+    /** Canon the previous episode established — ids AND the author's text. */
+    canonFacts: Array<{
+        factId: string;
+        text: string;
+    }>;
+    canonFactsTruncated: boolean;
+    /** Where the characters stand. Public by definition. */
+    relations: Array<{
+        between: [string, string];
+        descriptor: string;
+    }>;
+    relationsTruncated: boolean;
+    /** Declared nodes the previous episode never completed. */
+    unresolvedThreads: Array<{
+        nodeId: string;
+        objective: string;
+    }>;
+    unresolvedThreadsTruncated: boolean;
+    /** Declared facts never revealed — setups it did not pay off. Not called
+     *  "promises": a promise is something a character made, which this system
+     *  does not model. */
+    unfulfilledSetups: Array<{
+        factId: string;
+        text: string;
+    }>;
+    unfulfilledSetupsTruncated: boolean;
+}
+export interface WorldNextEpisodeResponse {
+    /** False on a retry that landed on the run already started. */
+    created: boolean;
+    episode: {
+        seriesId: string;
+        episodeId: string;
+        episodeRunId: string;
+        status: 'active' | 'ended';
+        startedAt: string;
+        startedAtRevision: number;
+        startedFromEpisodeId?: string;
+        startedFromEndingId?: string;
+    };
+    carryover: WorldCarryoverV1;
+}
 export interface WorldTurnReadback {
     turnId: string;
     worldInstanceId: string;
@@ -892,6 +965,77 @@ export declare class PouchyWorldClient {
         contentHash: string;
     }>;
     getWorld(environmentId: string): Promise<unknown>;
+    /** The world's readiness and operational aggregate — what the dashboard's
+     *  World Overview binds to.
+     *
+     *  This is the call to make BEFORE driving anything: `ready` plus the
+     *  `blockers` that explain a false, instance counts, and the delivery
+     *  queue's shape. It was reachable on both planes from the start and simply
+     *  had no method here, which meant the README's own credential table
+     *  promised an `adminKey` read the SDK could not perform. */
+    getWorldOverview(environmentId: string): Promise<unknown>;
+    /** What this world has cost, by month.
+     *
+     *  `months` is clamped server-side; omit it for the default window. */
+    getWorldCost(environmentId: string, months?: number): Promise<unknown>;
+    /** Every published revision of this world.
+     *
+     *  An instance is pinned to the revision it was created on, so this is how a
+     *  backend learns which definition a running story is actually playing. */
+    listWorldVersions(environmentId: string): Promise<{
+        versions: unknown[];
+    }>;
+    /** Every published revision of a story package.
+     *
+     *  The response carries `hasUnsupported` / `unsupportedCount` as well as the
+     *  versions: a history this build cannot read whole is reported as PARTIAL
+     *  rather than passing its newest readable revision off as the newest one.
+     *  Check that flag before treating the last entry as current. */
+    listStoryPackageVersions(packageId: string): Promise<{
+        versions: unknown[];
+        unsupported?: unknown;
+        unsupportedCount?: number;
+        hasUnsupported?: boolean;
+    }>;
+    /** Stop (or restart) a world.
+     *
+     *  A disabled world refuses new sessions and new turns. Existing instances
+     *  are not deleted and their ledgers are untouched — this is a door being
+     *  shut, not history being erased, and passing `false` opens it again. */
+    setWorldDisabled(environmentId: string, disabled: boolean): Promise<{
+        environmentId: string;
+        disabled: boolean;
+    }>;
+    /** Stop (or restart) a story package.
+     *
+     *  Worlds already PINNED to one of its revisions keep running: an instance
+     *  holds its own revision for life. This stops new pins. */
+    setStoryPackageDisabled(packageId: string, disabled: boolean): Promise<{
+        packageId: string;
+        disabled: boolean;
+    }>;
+    /** The pre-launch checklist for a world: every reason it would refuse to
+     *  run, gathered before you try.
+     *
+     *  OWNER TOKEN ONLY — there is no `/admin` mirror for this route, so an
+     *  unattended backend cannot call it. That is not an oversight to work
+     *  around: `getWorldOverview` carries `ready` and `blockers` and IS
+     *  mirrored, so a machine has the readiness answer it needs. */
+    preflightWorld(environmentId: string): Promise<unknown>;
+    /** Start the NEXT episode of a worldline that just finished one.
+     *
+     *  The worldline does NOT restart. Its `worldInstanceId`, membership, state
+     *  and ledger all continue — that is the point — and this moves the episode
+     *  on and hands back the CARRYOVER: what the next episode gets to stand on.
+     *
+     *  Idempotent. The run id is derived from the worldline, the episode and the
+     *  revision it starts at, so a retried call lands on the same run and
+     *  answers `created: false` rather than forking the story.
+     *
+     *  OWNER TOKEN ONLY — no `/admin` mirror, on the same reasoning as
+     *  `preflightWorld`: the mirror carries reads, and this is the write that
+     *  decides a story moves on. */
+    startNextEpisode(environmentId: string, worldInstanceId: string): Promise<WorldNextEpisodeResponse>;
     /** 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

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.19.0';
+export const WORLD_SDK_VERSION = '0.22.0';
 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
@@ -287,6 +287,81 @@ export class PouchyWorldClient {
     getWorld(environmentId) {
         return this.machine('GET', `/projects/${this.projectId}/environments/${environmentId}`, `/admin/environments/${environmentId}`);
     }
+    /** The world's readiness and operational aggregate — what the dashboard's
+     *  World Overview binds to.
+     *
+     *  This is the call to make BEFORE driving anything: `ready` plus the
+     *  `blockers` that explain a false, instance counts, and the delivery
+     *  queue's shape. It was reachable on both planes from the start and simply
+     *  had no method here, which meant the README's own credential table
+     *  promised an `adminKey` read the SDK could not perform. */
+    getWorldOverview(environmentId) {
+        return this.machine('GET', `/projects/${this.projectId}/environments/${environmentId}/overview`, `/admin/environments/${environmentId}/overview`);
+    }
+    /** What this world has cost, by month.
+     *
+     *  `months` is clamped server-side; omit it for the default window. */
+    getWorldCost(environmentId, months) {
+        const query = months === undefined ? '' : `?months=${encodeURIComponent(String(months))}`;
+        return this.machine('GET', `/projects/${this.projectId}/environments/${environmentId}/cost`, `/admin/environments/${environmentId}/cost`, undefined, query);
+    }
+    /** Every published revision of this world.
+     *
+     *  An instance is pinned to the revision it was created on, so this is how a
+     *  backend learns which definition a running story is actually playing. */
+    listWorldVersions(environmentId) {
+        return this.machine('GET', `/projects/${this.projectId}/environments/${environmentId}/versions`, `/admin/environments/${environmentId}/versions`);
+    }
+    /** Every published revision of a story package.
+     *
+     *  The response carries `hasUnsupported` / `unsupportedCount` as well as the
+     *  versions: a history this build cannot read whole is reported as PARTIAL
+     *  rather than passing its newest readable revision off as the newest one.
+     *  Check that flag before treating the last entry as current. */
+    listStoryPackageVersions(packageId) {
+        return this.machine('GET', `/projects/${this.projectId}/story-packages/${packageId}/versions`, `/admin/story-packages/${packageId}/versions`);
+    }
+    /** Stop (or restart) a world.
+     *
+     *  A disabled world refuses new sessions and new turns. Existing instances
+     *  are not deleted and their ledgers are untouched — this is a door being
+     *  shut, not history being erased, and passing `false` opens it again. */
+    setWorldDisabled(environmentId, disabled) {
+        return this.machine('POST', `/projects/${this.projectId}/environments/${environmentId}/disable`, `/admin/environments/${environmentId}/disable`, { disabled });
+    }
+    /** Stop (or restart) a story package.
+     *
+     *  Worlds already PINNED to one of its revisions keep running: an instance
+     *  holds its own revision for life. This stops new pins. */
+    setStoryPackageDisabled(packageId, disabled) {
+        return this.machine('POST', `/projects/${this.projectId}/story-packages/${packageId}/disable`, `/admin/story-packages/${packageId}/disable`, { disabled });
+    }
+    /** The pre-launch checklist for a world: every reason it would refuse to
+     *  run, gathered before you try.
+     *
+     *  OWNER TOKEN ONLY — there is no `/admin` mirror for this route, so an
+     *  unattended backend cannot call it. That is not an oversight to work
+     *  around: `getWorldOverview` carries `ready` and `blockers` and IS
+     *  mirrored, so a machine has the readiness answer it needs. */
+    preflightWorld(environmentId) {
+        return this.owner('GET', `/projects/${this.projectId}/environments/${environmentId}/preflight`);
+    }
+    /** Start the NEXT episode of a worldline that just finished one.
+     *
+     *  The worldline does NOT restart. Its `worldInstanceId`, membership, state
+     *  and ledger all continue — that is the point — and this moves the episode
+     *  on and hands back the CARRYOVER: what the next episode gets to stand on.
+     *
+     *  Idempotent. The run id is derived from the worldline, the episode and the
+     *  revision it starts at, so a retried call lands on the same run and
+     *  answers `created: false` rather than forking the story.
+     *
+     *  OWNER TOKEN ONLY — no `/admin` mirror, on the same reasoning as
+     *  `preflightWorld`: the mirror carries reads, and this is the write that
+     *  decides a story moves on. */
+    startNextEpisode(environmentId, worldInstanceId) {
+        return this.owner('POST', `/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/episodes/next`, {});
+    }
     /** 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

package/package.json

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