@pouchy_ai/world-sdk 0.8.0

package/CHANGELOG.md

@@ -0,0 +1,142 @@
+# @pouchy_ai/world-sdk
+
+## 0.8.0
+
+- `WorldDeliveryOpsRow` gained `cleanupRetryCount` and `cleanupStalledAt`.
+- These surface the Batch 7.2 atomic receipt cleanup: when a settled row and
+  its two delivery receipts are purged, all three go in one transaction, so a
+  refused delete now leaves the row intact with a retry scheduled instead of
+  orphaning a receipt whose routing was just deleted. `cleanupRetryCount` is how
+  many times that cleanup has failed; `cleanupStalledAt` is stamped once it
+  crosses the retry threshold and becomes an operator signal. Both are absent on
+  an ordinary row, and neither is a delivery status — a row carrying them is
+  still `delivered`.
+- No method changed shape.
+
+## 0.7.1
+
+- `WorldInstanceMetrics.delivery` gained `receiptCount` and
+  `eligibleForCleanup`. Delivery receipts are now collected when the outbox row
+  they proved is purged — the moment the last legal path back into delivery
+  closes — so a world running for months no longer accumulates them without
+  bound.
+- No method changed shape.
+
+## 0.7.0
+
+Additive: the dead-letter recovery terminal states.
+
+- `rehydrateDelivery`, `resolveDeliveryGap`, `describeDeliveryResolution`, and
+  the `WorldRehydrateFailure` type.
+- `WorldDeliveryOpsRow.status` gained `rehydrating`, `unrecoverable` and
+  `resolved_gap`, plus `rehydratedAt` / `rehydratedFrom` /
+  `unrecoverableReason` / `resolvedGapAt` / `replacesDeliveryId`.
+- Closes a loop 0.4.0 left open: a dead letter blocks its session, its text is
+  redacted after 30 days, and a redacted row refuses requeue. `rehydrateDelivery`
+  rebuilds it from the committed ledger (or the verified archive) and accepts the
+  result only if it re-derives the same delivery id and content digest;
+  `resolveDeliveryGap` is the last resort and takes no text.
+- `requeueDelivery` now refuses `unrecoverable` and `rehydrating` explicitly
+  rather than reporting them as already-queued — they block, and saying
+  otherwise would tell you the stream is moving when it is stopped.
+- No existing method changed shape.
+
+## 0.6.0
+
+Additive: the production hand-off.
+
+- `createApprovedExport`, `listApprovedExports`, `deriveStoryPackageCandidate`,
+  and the `ApprovedScriptExportRow` type.
+- An export carries lineage from the original story package through the world
+  instance, ledger range, evidence draft and editorial draft to the reviewer who
+  approved it. It is idempotent on content: the same approved review exports to
+  the same id forever, so replaying one is a no-op rather than a second script.
+- `notify` sends `world.script_approved` to the project's webhooks with lineage
+  and identifiers — never the script body, which a webhook payload should not
+  scatter across logs and proxies. Fetch the body over the authenticated route.
+- `deriveStoryPackageCandidate` returns a VALIDATED candidate and publishes
+  nothing. Only evidence-origin material becomes canon.
+- No existing method changed shape.
+
+## 0.5.0
+
+Additive: the refusal taxonomy.
+
+- `WorldRejectionCode` and `isDefectRejection`. `rejectedEffects[].code` now
+  travels on `WorldTurnResult`, and `WorldInstanceMetrics.turns` carries
+  `rejectionsByCode` plus the per-code rates.
+- Only `narrative_conflict` describes content — two characters wanted
+  incompatible things and the story rule settled it. Every other code is a
+  defect in the story package, the prompt or the integration. Treat the
+  aggregate `effectRejectionRate` as a mixed number and read the split instead.
+- `code` is absent on turns committed before this version. Read that as unknown,
+  never as narrative.
+- No existing method changed shape.
+
+## 0.4.0
+
+Additive: the dead-letter operating loop.
+
+- `listDeliveries`, `getDelivery`, `drainDeliveries`, `requeueDelivery`, and the
+  `describeDelivery` helper — plus `WorldDeliveryOpsRow`, `WorldDeliveryPage`,
+  `WorldDeliveryDetail` and `WorldDrainReport`.
+- `requeueDelivery` takes no payload parameter, on purpose: the beat was
+  committed by the coordinator, and supplying a different line here would be
+  authoring world history through the delivery plane. It is idempotent, refuses
+  a delivered row, and refuses one whose payload has aged out (30 days).
+- There is no discard method, and there is not going to be one.
+- `getDelivery({ includePayload: true })` writes an audit row naming the reader.
+- No existing method changed shape.
+
+## 0.3.1
+
+- `WorldInstanceMetrics.delivery` gained `blockedSessions`: delivery is now
+  ordered per target session, so a stuck line holds the ones behind it in that
+  session (and only that session). This is the count of readers currently
+  missing a beat.
+- No method changed shape.
+
+## 0.3.0
+
+Additive: operations.
+
+- `getWorldMetrics` — delivery and turn metric families for one instance, with
+  the `WorldInstanceMetrics` type.
+- `evaluateWorld` — run the `drama` or `npc` quality suite over an instance's
+  committed history, with the `WorldEvalReport` type. Deterministic: no model
+  judges the output.
+- `archiveLedger` — ledger archival, defaulting to the dry-run `plan`.
+  `execute` copies into immutable hash-chained segments and deletes nothing;
+  `prune` is the only call in this client that destroys a row, and it refuses
+  without `confirm` and again unless the archive verifies and has outlived its
+  retention.
+- No existing method changed shape.
+
+## 0.2.0
+
+Additive: the EDITORIAL layer over script drafts.
+
+- `createEditorialDraft`, `getEditorialDraft`, `listEditorialDrafts`,
+  `setEditorialStatus`, `decideEditorialScene`, `exportEditorialDraft`, and the
+  `EditorialDraftRow` type.
+- The deterministic script draft is unchanged and is never rewritten by this
+  layer; an editorial draft is stored beneath its evidence draft. Lines the
+  model cannot be shown to have taken from the committed record are recorded as
+  suggestions, and suggestions never enter world canon.
+- No existing method changed shape.
+
+## 0.1.0
+
+First release. Server-side client for the Pouchy World plane:
+
+- authoring: story packages and world definitions (both immutable-versioned,
+  both idempotent on content bytes);
+- running: world sessions, coordinated turns, trusted events — the machine lane
+  with a Secret Key plus a POUCHY-SOURCE-V1 signature over the exact body;
+- reading: world state (user projection), committed turn read-back, bounded
+  resumable ledger replay;
+- content return: script draft generation, review and export;
+- helpers: request signing, turn-id idempotency, typed errors with a
+  `retryable` verdict, and `describeTurn` for reading a result without
+  guessing which of execution and delivery a status refers to;
+- `conformance.mjs`: a runnable check of an integration end to end.

package/LICENSE

@@ -0,0 +1,41 @@
+Pouchy Companion SDK License
+Copyright (c) 2026 Pouchy.ai. All Rights Reserved.
+
+This license governs use of the "@pouchy_ai/companion-sdk" software package (the
+"SDK") as published to the npm registry. The SDK is proprietary software owned
+by Pouchy.ai. By installing, copying, or using the SDK you agree to these terms.
+
+1. GRANT. Subject to these terms, Pouchy.ai grants you a worldwide,
+   non-exclusive, non-transferable, royalty-free, revocable license to install
+   and use the SDK, as distributed, solely to build and operate applications
+   that integrate with Pouchy.ai's official services and APIs.
+
+2. RESTRICTIONS. Except to the extent a restriction below is prohibited by
+   applicable law, you may not:
+   (a) modify, adapt, or create derivative works of the SDK's source for
+       redistribution;
+   (b) redistribute, sublicense, sell, rent, or lease the SDK as a standalone
+       product, or republish it under a different name;
+   (c) reverse engineer, decompile, or disassemble the SDK except to the extent
+       necessary for interoperability and expressly permitted by law;
+   (d) use the SDK to build or operate a service that competes with Pouchy.ai's
+       services, or to access Pouchy.ai's services in violation of their terms;
+   (e) remove or alter any copyright, trademark, or other proprietary notices.
+
+3. RESERVATION OF RIGHTS. All rights not expressly granted are reserved by
+   Pouchy.ai. No rights are granted in Pouchy.ai's source repositories,
+   trademarks, or services beyond what is needed to use the SDK as described.
+
+4. TERMINATION. This license terminates automatically if you breach it. On
+   termination you must stop using and delete all copies of the SDK.
+
+5. NO WARRANTY. THE SDK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+6. LIMITATION OF LIABILITY. IN NO EVENT SHALL POUCHY.AI BE LIABLE FOR ANY CLAIM,
+   DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR
+   OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SDK OR THE USE OR
+   OTHER DEALINGS IN THE SDK.
+
+For any other use, or for written permission, contact legal@pouchy.ai.

package/README.md

@@ -0,0 +1,141 @@
+# @pouchy_ai/world-sdk
+
+Server-side TypeScript client for **Pouchy World** — build an interactive short
+drama, a game's NPC cast, or an interactive novel on top of Pouchy, without an
+official app.
+
+```bash
+npm i @pouchy_ai/world-sdk
+```
+
+Node ≥ 18, zero dependencies.
+
+## Node only. Really.
+
+This client holds a project **Secret Key** (`pchy_sk_…`) and an event-source
+**signing secret** (`pesk_…`). They never belong in a browser or a mobile app.
+The world's machine lane requires BOTH — a key proves the project and its
+test/live axis, a signature proves the provider — and a leaked pair is a world
+anyone can drive.
+
+What your users' devices get is the **session token** this client mints for
+them, which is scoped to one world instance and one role and carries no project
+credential. Drive that with `@pouchy_ai/companion-sdk`.
+
+## The two lanes
+
+| Lane | Credential | What it does |
+|---|---|---|
+| 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 |
+
+```ts
+import { PouchyWorldClient, newTurnId, describeTurn } from '@pouchy_ai/world-sdk';
+
+const world = new PouchyWorldClient({
+  projectId: process.env.POUCHY_PROJECT_ID!,
+  adminToken: process.env.POUCHY_ADMIN_TOKEN!,
+  secretKey: process.env.POUCHY_SECRET_KEY!,
+  signing: { source: 'drama-backend', keyId: process.env.KID!, secret: process.env.SECRET! }
+});
+```
+
+## What it covers
+
+**Authoring** — `createStoryPackage`, `publishStoryPackage`, `getStoryPackage`,
+`listStoryPackages`, `createWorld`, `publishWorld`, `getWorld`, `listWorlds`.
+
+**Running** — `createWorldSession`, `runTurn`, `sendEvent`.
+
+**Reading** — `getWorldState`, `getTurn`, `replayLedger`, `replayLedgerToEnd`.
+
+**Content return** — `createScriptDraft`, `getScriptDraft`, `listScriptDrafts`,
+`reviewScriptDraft`, `exportScriptDraft`.
+
+**Delivery ops** — `listDeliveries`, `getDelivery`, `drainDeliveries`,
+`requeueDelivery`, `describeDelivery`. Deliveries land in ledger order per
+session, so a stuck line holds the ones behind it in that session (and only
+that session) — `blocking` on a row is a reader who has stopped receiving the
+story. `requeueDelivery` is the way out; it takes no payload, because the beat
+was committed by the coordinator and re-writing it here would make the delivery
+plane a second authoring path. There is no discard.
+
+**Stuck deliveries** — `rehydrateDelivery`, `resolveDeliveryGap`,
+`describeDeliveryResolution`. Three verbs in the order to try them: re-send what
+is still there, rebuild it from the committed record, or tell the reader the
+beat is gone. None of them accepts replacement text, and none of them skips a
+beat silently — `resolved_gap` means the reader was told, and it is the only
+non-delivered state a session moves past.
+
+**Operations** — `getWorldMetrics`, `evaluateWorld`, `archiveLedger`,
+`replayLedger` / `replayLedgerToEnd`. Metrics keep delivery and turn health as
+separate families; the eval suites are deterministic, so a score can be
+regressed. `archiveLedger` defaults to a dry-run plan, `execute` only ever
+copies, and `prune` — the one call here that deletes — refuses without
+`confirm`, and again unless the archive verifies and has outlived retention.
+
+**Production hand-off** — `createApprovedExport`, `listApprovedExports`,
+`deriveStoryPackageCandidate`. An approved editorial draft becomes a versioned
+`ApprovedScriptExportV1` carrying the whole chain: original story package →
+world instance → ledger range → evidence draft → editorial draft → reviewer.
+Idempotent on content, so replaying an export is a no-op. The Story Package
+candidate is validated and *returned*; publishing it is a separate act by a
+person, and only evidence-origin material becomes canon.
+
+**Editorial layer** — `createEditorialDraft`, `getEditorialDraft`,
+`listEditorialDrafts`, `setEditorialStatus`, `decideEditorialScene`,
+`exportEditorialDraft`. The script draft is deterministic: it is assembled from
+committed ledger entries and nothing else, and nothing rewrites it. The
+editorial draft is a model's *reading* of that draft — scenes, ordering,
+connective prose — stored underneath it. Every line the model presents as
+something a character said is re-checked against the committed record on the
+server; anything that does not match is stored as `origin: "suggestion"`,
+whatever the model labelled it. Suggestions never reach world canon, and only
+an `approved` editorial can be exported.
+
+**Helpers** — `signSourceRequest` (the exact canonical the server verifies),
+`newTurnId` / `isReservedTurnId` (idempotency), `describeTurn` (read a result
+without guessing), `WorldApiError` with typed codes and `.retryable`.
+
+## 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.
+
+**3. Execution and delivery are different questions.** `executionStatus` says
+whether the world moved; `deliveryStatus` says whether the audience has heard
+about it yet. A `pending` delivery is not a failed turn — the intent was
+written inside the commit and a durable outbox is retrying it.
+
+```ts
+const beat = await world.runTurn({ environmentId, worldInstanceId, text: '…' });
+const read = describeTurn(beat);
+if (read.shouldRetrySameTurn) { /* conflict — re-send the SAME turnId */ }
+if (read.needsDifferentRequest) { /* rejected/refused — fix it, use a NEW id */ }
+```
+
+## Conformance
+
+```bash
+node node_modules/@pouchy_ai/world-sdk/conformance.mjs
+```
+
+Checks your credentials, signing, world resolution, role bindings, a real turn,
+turn recovery, state read, replay and draft generation against your OWN
+project — before you write product code. It prints a pass/fail line per check
+and exits non-zero on the first structural failure.
+
+## Quickstarts
+
+- `docs/world-quickstart-drama.md` — screenplay → world → new screenplay draft
+- `docs/world-quickstart-npc.md` — one town, three NPCs, one shared state
+
+## License
+
+See LICENSE.

package/conformance.mjs

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+// Pouchy World — conformance runner.
+//
+// Checks an integration END TO END against a real project, before any product
+// code exists: credentials, the exact signing canonical, world resolution, role
+// bindings, capability intersection, a real coordinated turn, turn recovery,
+// state reads, replay verification and draft generation.
+//
+// It is deliberately a script rather than a test suite: an integrator running
+// this has no repository, no vitest and no fixtures — they have a terminal, a
+// project, and a question about whether their setup is right.
+//
+// Nothing here is destructive: it creates a story package, a world and one
+// session in YOUR project (all versioned, all disable-able), drives one beat,
+// and reads. It never deletes and never publishes anything to end users.
+//
+// Two scenarios, because the two products fail differently and an integrator
+// should check the one they are building. `--scenario=drama` casts two
+// characters who both speak in a beat; `--scenario=npc` casts a merchant who
+// 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_SOURCE=… POUCHY_SOURCE_KID=… POUCHY_SOURCE_SECRET=… \
+//   POUCHY_AGENT_A=… POUCHY_AGENT_B=… node conformance.mjs [--scenario=drama|npc]
+
+import { PouchyWorldClient, newTurnId, describeTurn, WorldApiError } from './dist/index.js';
+
+const env = (name, required = true) => {
+	const value = process.env[name];
+	if (!value && required) {
+		console.error(`MISSING ${name}`);
+		process.exit(2);
+	}
+	return value;
+};
+
+/** The two shapes an integrator can be building. Same plane, different cast,
+ *  and a different question at the end of the beat. */
+const SCENARIOS = {
+	drama: {
+		label: 'short drama',
+		roles: [
+			{ storyRoleId: 'heroine', worldRoleId: 'heroine', effectsAllow: ['set_flag'] },
+			{ storyRoleId: 'rival', worldRoleId: 'rival', effectsAllow: ['set_flag'] }
+		],
+		scenes: [{ sceneId: 'docks', title: 'Docks', description: 'After rain, before dawn.' }],
+		nodes: [
+			{ nodeId: 'n1', sceneId: 'docks', title: 'Meet', objective: 'they meet', prerequisites: [] }
+		],
+		flags: [{ key: 'tension', kind: 'number', initial: 0 }],
+		leadRole: 'heroine',
+		prompt: 'Conformance check: you two have just met at the docks. One short line each.',
+		// A drama is wrong when only one voice comes back.
+		expect: (beat) => {
+			if ((beat.roleMessages ?? []).length < 2) {
+				throw new Error(`a drama beat returned ${(beat.roleMessages ?? []).length} line(s); both roles should speak`);
+			}
+			return `${beat.roleMessages.length} roles spoke`;
+		}
+	},
+	npc: {
+		label: 'game NPC',
+		roles: [
+			{ storyRoleId: 'merchant', worldRoleId: 'merchant', effectsAllow: ['set_flag'] },
+			{ storyRoleId: 'guard', worldRoleId: 'guard' }
+		],
+		scenes: [{ sceneId: 'market', title: 'Market', description: 'A stall at the gate.' }],
+		nodes: [
+			{ nodeId: 'n1', sceneId: 'market', title: 'Trade', objective: 'a price is agreed', prerequisites: [] }
+		],
+		flags: [{ key: 'stock', kind: 'number', initial: 3 }],
+		leadRole: 'merchant',
+		prompt: 'Conformance check: a player asks your price for one lamp. Answer briefly.',
+		// An NPC is wrong when it talks and the world does not move.
+		expect: (beat) => {
+			if (!(beat.roleMessages ?? []).length) throw new Error('no NPC answered');
+			const moved = (beat.committedStateDiff ?? []).length > 0;
+			return moved
+				? `${beat.roleMessages.length} answered, ${beat.committedStateDiff.length} state op(s)`
+				: `${beat.roleMessages.length} answered, world state unchanged (check effectsAllow if this is unexpected)`;
+		}
+	}
+};
+const scenarioName = (process.argv.find((a) => a.startsWith('--scenario=')) ?? '--scenario=drama')
+	.split('=')[1];
+const scenario = SCENARIOS[scenarioName];
+if (!scenario) {
+	console.error(`unknown --scenario=${scenarioName}; expected one of: ${Object.keys(SCENARIOS).join(', ')}`);
+	process.exit(2);
+}
+console.log(`Pouchy World conformance — ${scenario.label} scenario\n`);
+
+const results = [];
+let failed = false;
+
+async function check(name, fn) {
+	try {
+		const detail = await fn();
+		results.push({ name, ok: true, detail });
+		console.log(`PASS  ${name}${detail ? ` — ${detail}` : ''}`);
+	} catch (err) {
+		failed = true;
+		const detail =
+			err instanceof WorldApiError
+				? `${err.code} ${err.status}${err.detail ? `: ${err.detail}` : ''}`
+				: err instanceof Error
+					? err.message
+					: String(err);
+		results.push({ name, ok: false, detail });
+		console.error(`FAIL  ${name} — ${detail}`);
+	}
+}
+
+const world = new PouchyWorldClient({
+	projectId: env('POUCHY_PROJECT_ID'),
+	adminToken: env('POUCHY_ADMIN_TOKEN'),
+	secretKey: env('POUCHY_SECRET_KEY'),
+	signing: {
+		source: env('POUCHY_SOURCE'),
+		keyId: env('POUCHY_SOURCE_KID'),
+		secret: env('POUCHY_SOURCE_SECRET')
+	},
+	...(process.env.POUCHY_BASE_URL ? { baseUrl: process.env.POUCHY_BASE_URL } : {})
+});
+const agentA = env('POUCHY_AGENT_A');
+const agentB = env('POUCHY_AGENT_B');
+const stamp = Date.now().toString(36);
+
+let pkg;
+let created;
+let instanceId;
+let turnId;
+
+await check('owner credential resolves the project', async () => {
+	const list = await world.listStoryPackages();
+	return `${(list.packages ?? []).length} story package(s) visible`;
+});
+
+await check('story package imports and pins', async () => {
+	pkg = await world.createStoryPackage({
+		name: `Conformance ${scenarioName} ${stamp}`,
+		summary: `Generated by the Pouchy World conformance runner (${scenario.label}).`,
+		roles: scenario.roles,
+		scenes: scenario.scenes,
+		nodes: scenario.nodes,
+		stateSchema: { flags: scenario.flags }
+	});
+	return `${pkg.packageId} rev ${pkg.revision}`;
+});
+
+await check('world publishes with an EXPLICIT coordinated runtime', async () => {
+	created = await world.createWorld({
+		name: `Conformance World ${stamp}`,
+		providerRef: env('POUCHY_SOURCE'),
+		runtimeMode: 'coordinated',
+		storyPackageRef: {
+			packageId: pkg.packageId,
+			revision: pkg.revision,
+			contentHash: pkg.contentHash
+		},
+		capabilityAllow: { views: [], actions: [], events: [] },
+		roles: [
+			{ roleId: scenario.roles[0].worldRoleId, agentId: agentA },
+			{ roleId: scenario.roles[1].worldRoleId, agentId: agentB }
+		]
+	});
+	return `${created.environmentId} rev ${created.environmentRevision}`;
+});
+
+await check('session mint binds one user to one role (machine lane)', async () => {
+	const session = await world.createWorldSession({
+		environment: created.environmentId,
+		role: scenario.leadRole,
+		externalUserId: `conformance-${scenarioName}-${stamp}`
+	});
+	instanceId = session?.world?.instance ?? session?.world?.world_instance;
+	if (!instanceId) throw new Error('no world instance in the session payload');
+	if (!session.token) throw new Error('no session token minted');
+	return instanceId;
+});
+
+await check('a signed turn runs a coordinated beat', async () => {
+	turnId = newTurnId('conformance');
+	const beat = await world.runTurn({
+		environmentId: created.environmentId,
+		worldInstanceId: instanceId,
+		turnId,
+		text: scenario.prompt
+	});
+	const read = describeTurn(beat);
+	if (!beat.selectedRoles?.length && beat.completionStatus === 'refused') {
+		throw new Error(`refused: ${beat.rejectedEffects?.[0]?.reason ?? 'unknown'}`);
+	}
+	// The scenario's own question — a drama that returns one voice and an NPC
+	// that never touches the world both pass every generic check above.
+	return `${read.summary}; ${scenario.expect(beat)}`;
+});
+
+await check('the SAME turnId is idempotent (no second beat)', async () => {
+	const again = await world.runTurn({
+		environmentId: created.environmentId,
+		worldInstanceId: instanceId,
+		turnId,
+		text: 'Conformance check: say one short line in character.'
+	});
+	if (again.completionStatus !== 'duplicate') {
+		throw new Error(`expected duplicate, got ${again.completionStatus}`);
+	}
+	return 'duplicate, nothing advanced';
+});
+
+await check('a committed turn is recoverable by id', async () => {
+	const recovered = await world.getTurn(created.environmentId, instanceId, turnId);
+	if (recovered.turnId !== turnId) throw new Error('turn read back with a different id');
+	return `${(recovered.roleMessages ?? []).length} line(s) on the record`;
+});
+
+await check('world state reads back (user projection, no private layer)', async () => {
+	const { state } = await world.getWorldState(created.environmentId, instanceId);
+	if (typeof state.stateRevision !== 'number') throw new Error('no stateRevision');
+	if ('rolePrivate' in state) throw new Error('the user projection leaked the private layer');
+	return `revision ${state.stateRevision}`;
+});
+
+await check('replay verifies the ledger against the served state', async () => {
+	const report = await world.replayLedgerToEnd(created.environmentId, instanceId);
+	if (report.verdict !== 'consistent') {
+		throw new Error(`${report.verdict}${report.detail ? `: ${report.detail}` : ''}`);
+	}
+	if (report.dryRun !== true) throw new Error('replay did not report itself as a dry run');
+	return `consistent over ${report.entriesScanned} entr(ies)`;
+});
+
+await check('a script draft generates and refuses export before review', async () => {
+	const draft = await world.createScriptDraft(created.environmentId, instanceId);
+	if (draft.content?.humanReviewRequired !== true) {
+		throw new Error('draft did not carry humanReviewRequired');
+	}
+	try {
+		await world.exportScriptDraft(created.environmentId, instanceId, draft.draftId);
+		throw new Error('export succeeded WITHOUT a human review');
+	} catch (err) {
+		if (!(err instanceof WorldApiError) || err.status !== 409) throw err;
+	}
+	return `${draft.draftId} (export correctly refused)`;
+});
+
+await check('a WRONG signature is refused (the second proof is real)', async () => {
+	const bad = new PouchyWorldClient({
+		projectId: env('POUCHY_PROJECT_ID'),
+		secretKey: env('POUCHY_SECRET_KEY'),
+		signing: {
+			source: env('POUCHY_SOURCE'),
+			keyId: env('POUCHY_SOURCE_KID'),
+			secret: 'pesk_not_the_real_secret'
+		},
+		...(process.env.POUCHY_BASE_URL ? { baseUrl: process.env.POUCHY_BASE_URL } : {})
+	});
+	try {
+		await bad.runTurn({
+			environmentId: created.environmentId,
+			worldInstanceId: instanceId,
+			text: 'this must not run'
+		});
+		throw new Error('a bad signature was ACCEPTED');
+	} catch (err) {
+		if (!(err instanceof WorldApiError) || err.status !== 403) throw err;
+	}
+	return 'refused with 403, as it must be';
+});
+
+console.log('');
+console.log(`${results.filter((r) => r.ok).length}/${results.length} checks passed`);
+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.');