@pouchy_ai/world-sdk 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @pouchy_ai/world-sdk
 
+## 0.16.0
+
+- `scanConsistency()` — what a world's own record proves about itself. Ten
+  deterministic findings, each a comparison between committed facts and the
+  pinned story package. Read-only: it commits nothing, asks no model, and
+  repairs nothing.
+- **`code` is a closed set that may grow.** A published member is never removed,
+  renamed, or widened in meaning; a criterion found to be wrong is deprecated
+  and replaced beside it. Handle an unknown code as informational rather than
+  failing on it — that is what makes a minor bump safe to take.
+- **Read `coverage` before trusting an empty `findings`.** Some checks read
+  fields older ledger rows do not carry, and those entries are counted there
+  rather than skipped in silence. A clean report with non-empty coverage is
+  clean about less than the whole world.
+- `incomplete` is a status, not an empty result: the walk is capped, a `cursor`
+  comes back, and the state- and chain-level checks do not run on a partial
+  walk. `entriesScanned` stays honest even once `findingsTruncated` is true.
+- Rate limited on two axes (project and IP, 30/min each, both required).
+  `status: 'rate_limited'` arrives with HTTP 429 and `retryAfterSec`. If the
+  shared limiter is unreachable the scan still runs — a read-only diagnostic
+  should not vanish when a world is being investigated.
+
 ## 0.15.0
 
 - `getProgress()` — where a story is and whether it can go on, as a DERIVED

package/README.md

@@ -52,7 +52,7 @@ 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`.
+`listTurnsSince`, `replayLedger`, `replayLedgerToEnd`, `scanConsistency`.
 
 **Which credential does what.** This matters more than it looks: one of them
 expires within the hour.

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.15.0";
+export declare const WORLD_SDK_VERSION = "0.16.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. */
@@ -641,6 +641,65 @@ export interface WorldClientOptions {
      *  default is generous on purpose, and lower is usually wrong. */
     timeoutMs?: number;
 }
+/** What a world's own record proves about itself. World API 1.19.
+ *
+ *  DETERMINISTIC ONLY. Every finding is a comparison between committed facts
+ *  and the story package the instance pins — never a judgement about writing.
+ *  Nothing here repairs anything, and nothing here is a suggestion.
+ *
+ *  `code` is a CLOSED set that may GROW. A published member is never removed,
+ *  renamed, or widened in meaning; a criterion later found to be wrong is
+ *  deprecated and replaced beside it. So handle an unknown code as
+ *  informational rather than failing on it — that is what makes a minor bump
+ *  safe to take. */
+export type WorldConsistencyFindingCode = 'revision_mismatch' | 'ledger_drift' | 'ledger_missing_entries' | 'unrecorded_beat_claim' | 'orphan_branch_reference' | 'node_prereq_violation' | 'effect_without_grant' | 'flag_schema_violation' | 'relation_change_without_cause' | 'verbatim_secret_disclosure';
+export interface WorldConsistencyEvidence {
+    turnId?: string;
+    seq?: number;
+    roleId?: string;
+    sceneId?: string;
+    nodeId?: string;
+    branchId?: string;
+    flagKey?: string;
+    effectKind?: string;
+    /** Only on verbatim matches, and only the matched fragment — never a line. */
+    quote?: string;
+    /** Passed through from a committed rejection AS EVIDENCE. It is not this
+     *  finding's classification; the two vocabularies stay separate. */
+    ledgerRejectionCode?: string;
+}
+export interface WorldConsistencyFinding {
+    code: WorldConsistencyFindingCode;
+    layer: 'deterministic';
+    status: 'proven';
+    severity: 'blocking' | 'warning' | 'info';
+    /** Never empty. A finding nobody can check is an accusation. */
+    evidence: WorldConsistencyEvidence[];
+}
+/** What a check could NOT examine. Read this before trusting an empty
+ *  `findings`: a clean report with non-empty coverage is clean about less than
+ *  the whole world. Absence of a finding is not proof of absence. */
+export interface WorldConsistencyCoverage {
+    code: WorldConsistencyFindingCode;
+    skipped: number;
+    reason: 'evidence_field_absent' | 'scan_incomplete';
+}
+export type WorldConsistencyReport = {
+    status: 'complete' | 'incomplete';
+    contractVersion: number;
+    findings: WorldConsistencyFinding[];
+    coverage: WorldConsistencyCoverage[];
+    entriesScanned: number;
+    findingsTruncated: boolean;
+    /** Present only when `status` is `incomplete`. Pass it back to continue. */
+    cursor?: number;
+} | {
+    status: 'rate_limited';
+    retryAfterSec: number;
+} | {
+    status: 'unavailable';
+    reason: 'world_unavailable';
+};
 export declare class PouchyWorldClient {
     readonly projectId: string;
     private readonly baseUrl;
@@ -692,6 +751,28 @@ export declare class PouchyWorldClient {
         environmentRevision: number;
         state: Record<string, unknown>;
     }>;
+    /** What this world's own record proves about itself. World API 1.19.
+     *
+     *  A read-only scan: it commits nothing, asks no model, and repairs nothing.
+     *  Findings are deterministic — each one is two recorded things that cannot
+     *  both be true — so they are safe to act on without a human re-reading the
+     *  story, which is exactly what the model-assisted layer is not.
+     *
+     *  Check `status` first. `incomplete` means the walk was capped or the
+     *  datastore stopped answering: pass `cursor` back to continue, and do NOT
+     *  read an empty `findings` on that arm as a clean bill of health.
+     *
+     *  READ `coverage` BEFORE TRUSTING AN EMPTY `findings`. Some checks depend
+     *  on fields that older ledger rows do not carry, and those entries are
+     *  counted there rather than skipped in silence. A clean report that could
+     *  not examine half the history is not the same as a clean world.
+     *
+     *  Rate limited on two axes, project and IP. `status: 'rate_limited'`
+     *  arrives with HTTP 429 and `retryAfterSec`.
+     */
+    scanConsistency(environmentId: string, worldInstanceId: string, opts?: {
+        cursor?: number;
+    }): Promise<WorldConsistencyReport>;
     /** Where the story is, and whether it can go on. World API 1.18.
      *
      *  A DERIVED checkpoint: nothing is stored to answer it, no model is asked,

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.15.0';
+export const WORLD_SDK_VERSION = '0.16.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
@@ -297,6 +297,36 @@ export class PouchyWorldClient {
     getWorldState(environmentId, worldInstanceId) {
         return this.read(`/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/state`, `/admin/environments/${environmentId}/instances/${worldInstanceId}/state`);
     }
+    /** What this world's own record proves about itself. World API 1.19.
+     *
+     *  A read-only scan: it commits nothing, asks no model, and repairs nothing.
+     *  Findings are deterministic — each one is two recorded things that cannot
+     *  both be true — so they are safe to act on without a human re-reading the
+     *  story, which is exactly what the model-assisted layer is not.
+     *
+     *  Check `status` first. `incomplete` means the walk was capped or the
+     *  datastore stopped answering: pass `cursor` back to continue, and do NOT
+     *  read an empty `findings` on that arm as a clean bill of health.
+     *
+     *  READ `coverage` BEFORE TRUSTING AN EMPTY `findings`. Some checks depend
+     *  on fields that older ledger rows do not carry, and those entries are
+     *  counted there rather than skipped in silence. A clean report that could
+     *  not examine half the history is not the same as a clean world.
+     *
+     *  Rate limited on two axes, project and IP. `status: 'rate_limited'`
+     *  arrives with HTTP 429 and `retryAfterSec`.
+     */
+    scanConsistency(environmentId, worldInstanceId, opts = {}) {
+        // The query rides the third argument, not the path template. Both are
+        // sent identically; keeping the path a pure template is what lets the
+        // admin-lane gate check that every `/admin/...` the SDK sends is a route
+        // that actually exists.
+        const q = new URLSearchParams();
+        if (opts.cursor !== undefined)
+            q.set('cursor', String(opts.cursor));
+        const suffix = q.toString() ? `?${q}` : '';
+        return this.read(`/projects/${this.projectId}/environments/${environmentId}/instances/${worldInstanceId}/consistency`, `/admin/environments/${environmentId}/instances/${worldInstanceId}/consistency`, suffix);
+    }
     /** Where the story is, and whether it can go on. World API 1.18.
      *
      *  A DERIVED checkpoint: nothing is stored to answer it, no model is asked,

package/package.json

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