@pouchy_ai/world-sdk 0.8.0

package/dist/index.d.ts

@@ -0,0 +1,631 @@
+export declare const WORLD_SDK_VERSION = "0.1.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. */
+export declare const WORLD_ERROR_CODES: readonly ["unauthorized", "forbidden", "not_found", "conflict", "unprocessable", "rate_limited", "payload_too_large", "server_error", "network", "unknown"];
+export type WorldErrorCode = (typeof WORLD_ERROR_CODES)[number];
+export declare class WorldApiError extends Error {
+    readonly code: WorldErrorCode;
+    readonly status: number;
+    /** The server's own message, when it sent one. */
+    readonly detail?: string;
+    readonly retryAfterSec?: number;
+    constructor(input: {
+        code: WorldErrorCode;
+        status: number;
+        message: string;
+        detail?: string;
+        retryAfterSec?: number;
+    });
+    /** Worth trying again with the SAME idempotency key. A 409 is not: it means
+     *  the world disagreed with the request, and repeating it will disagree
+     *  again. */
+    get retryable(): boolean;
+}
+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
+ *  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.
+ *
+ *  Pass the same string you will actually send as the body. Serializing twice
+ *  (once to sign, once to send) is the classic way to sign bytes you did not
+ *  send. */
+export declare function signSourceRequest(input: {
+    source: string;
+    /** eventId for `/events`, turnId for the turns door — the id slot. */
+    id: string;
+    body: string;
+    keyId: string;
+    secret: string;
+    nowMs?: number;
+}): string;
+/** A fresh turn id for a NEW beat. Retrying a beat means re-sending the SAME
+ *  id — that is what makes the retry free of a second commit, a second model
+ *  call and a second message. Generate once, store it with whatever you are
+ *  about to do, and reuse it until you get an answer. */
+export declare function newTurnId(prefix?: string): string;
+/** `evt:` is the platform's own namespace for turns derived from trusted
+ *  events; the turns door refuses caller ids in it. */
+export declare function isReservedTurnId(turnId: string): boolean;
+export type WorldCompletionStatus = 'complete' | 'partial' | 'duplicate' | 'conflict' | 'rejected' | 'refused';
+export type WorldExecutionStatus = 'committed' | 'not_committed';
+export type WorldDeliveryStatus = 'delivered' | 'pending' | 'none';
+export interface WorldTurnResult {
+    turnId: string;
+    worldInstanceId: string;
+    beforeStateRevision: number;
+    afterStateRevision: number;
+    selectedRoles: string[];
+    roleMessages: Array<{
+        roleId: string;
+        message: string;
+        fallback?: true;
+    }>;
+    committedStateDiff: unknown[];
+    rejectedEffects: Array<{
+        index: number;
+        reason: string;
+        roleId?: string;
+        kind?: string;
+        /** Batch 7 — WHY, as a code. `narrative_conflict` is the only one that
+         *  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, and should be treated as one
+         *  rather than as colour. Absent on turns committed before the taxonomy —
+         *  read that as unknown, never as narrative. */
+        code?: WorldRejectionCode;
+    }>;
+    skippedRoles: Array<{
+        roleId: string;
+        reason: string;
+    }>;
+    nextOptions: Array<{
+        branchId: string;
+        condition: string;
+    }>;
+    repairs?: Array<{
+        roleId: string;
+        outcome: 'repaired' | 'fallback';
+        reason?: string;
+    }>;
+    traceId?: string;
+    executionStatus: WorldExecutionStatus;
+    deliveryStatus: WorldDeliveryStatus;
+    completionStatus: WorldCompletionStatus;
+}
+/** Read a turn result without guessing. The two questions are separate: did
+ *  the world move, and did the audience hear about it. */
+/** Read a delivery row without guessing what its status means. `blocking` is
+ *  the field that matters most: PR-A delivers a session's beats in order, so a
+ *  blocking row is not one failure — it is a reader who has stopped receiving
+ *  the story until someone acts. */
+/** Why a redacted dead letter could not be rebuilt. A closed vocabulary: an
+ *  operator deciding whether to resolve a gap is making a judgement call, and a
+ *  free-text reason is one they cannot compare across incidents. */
+export type WorldRehydrateFailure = 'source_missing' | 'archive_unavailable' | 'hash_mismatch' | 'ledger_drift' | 'identity_mismatch';
+/** What to DO about a stuck delivery, in one call. The three answers are the
+ *  three verbs, in the order they should be tried: re-send what is still there,
+ *  rebuild it from the record, or tell the reader the beat is gone. */
+export declare function describeDeliveryResolution(row: WorldDeliveryOpsRow): {
+    action: 'none' | 'requeue' | 'rehydrate' | 'resolve_gap' | 'wait';
+    blocking: boolean;
+    summary: string;
+};
+export declare function describeDelivery(row: WorldDeliveryOpsRow): {
+    state: 'landed' | 'in_flight' | 'waiting' | 'stuck';
+    blocking: boolean;
+    summary: string;
+};
+export declare function describeTurn(result: WorldTurnResult): {
+    worldMoved: boolean;
+    audienceHeard: boolean;
+    /** Sending the SAME turnId again is safe and correct. */
+    shouldRetrySameTurn: boolean;
+    /** The request itself needs changing before it can succeed. */
+    needsDifferentRequest: boolean;
+    summary: string;
+};
+export interface WorldReplayReport {
+    worldInstanceId: string;
+    verdict: 'consistent' | 'drift' | 'missing_entries' | 'illegal_patch' | 'incomplete' | 'unavailable';
+    detail?: string;
+    fromRevision: number;
+    rebuiltRevision: number;
+    rebuiltHash: string;
+    currentRevision: number | null;
+    currentHash: string | null;
+    entriesScanned: number;
+    cursor?: string;
+    checkpointWritten?: number;
+    saturated: boolean;
+    elapsedMs: number;
+    dryRun: true;
+}
+export interface ScriptDraftRow {
+    draftId: string;
+    jobId: string;
+    worldInstanceId: string;
+    environmentId: string;
+    content: Record<string, unknown>;
+    status: 'draft' | 'reviewed';
+    createdAt: string;
+    createdBy: string;
+    reviewedAt?: string;
+    reviewedBy?: string;
+    reviewNote?: string;
+}
+/** The EDITORIAL layer: a model's reading of an evidence draft, and the human
+ *  review state attached to it. `suggestionRatio` is the share of lines the
+ *  server could NOT match to a committed line — read it before you read the
+ *  prose. */
+export interface EditorialDraftRow {
+    editorialId: string;
+    draftId: string;
+    worldInstanceId: string;
+    environmentId: string;
+    content: {
+        contractVersion: number;
+        title: string;
+        scenes: Array<Record<string, unknown>>;
+        provenance: Record<string, unknown>;
+        suggestionRatio: number;
+        humanReviewRequired: true;
+    };
+    status: 'draft' | 'under_review' | 'changes_requested' | 'approved' | 'rejected' | 'exported';
+    sceneDecisions?: Record<string, Record<string, unknown>>;
+    createdAt: string;
+    createdBy: string;
+    updatedAt?: string;
+    statusBy?: string;
+    statusNote?: string;
+    exportedAt?: string;
+}
+/** Operator metrics for one world instance. Two families, kept apart on
+ *  purpose: one word answering both is how a delivery outage reads as a
+ *  content problem. */
+/** The shared refusal taxonomy (Batch 7). Only `narrative_conflict` is content. */
+export type WorldRejectionCode = 'narrative_conflict' | 'policy_rejection' | 'schema_rejection' | 'canon_rejection' | 'concurrency_rejection' | 'repair_failure';
+/** True for every code except `narrative_conflict`. */
+export declare function isDefectRejection(code: WorldRejectionCode | undefined): boolean;
+export interface WorldInstanceMetrics {
+    worldInstanceId: string;
+    generatedAt: number;
+    stateRevision: number | null;
+    delivery: {
+        byStatus: Record<string, number>;
+        retried: number;
+        attemptsTotal: number;
+        dead: number;
+        oldestUndeliveredAgeMs: number | null;
+        /** Sessions whose oldest unlanded line cannot move. Delivery is ordered
+         *  per session, so this is the number of readers currently missing a
+         *  beat — usually a dead letter holding the stream. */
+        blockedSessions: number;
+        /** Batch 7.1 — receipt growth on a long-running world, and how much of it
+         *  is collectable. A receipt exists for as long as any legal path can put
+         *  its delivery back in flight; `eligibleForCleanup` counts the delivered
+         *  rows past retention, which is the only population whose receipts go. */
+        receiptCount: number;
+        eligibleForCleanup: number;
+        latencyP50Ms: number | null;
+        latencyP95Ms: number | null;
+        scanned: number;
+        truncated: boolean;
+    };
+    turns: {
+        turns: number;
+        effectsProposed: number;
+        effectsAccepted: number;
+        effectsRejected: number;
+        effectRejectionRate: number;
+        /** Batch 7 — refusals split by the shared taxonomy. Judge a world by
+         *  these, not by the aggregate above: the aggregate mixes drama with
+         *  defects. */
+        rejectionsByCode: Record<WorldRejectionCode, number>;
+        narrativeConflictRate: number;
+        policyRejectionRate: number;
+        schemaRejectionRate: number;
+        canonRejectionRate: number;
+        concurrencyConflictRate: number;
+        repairAttemptRate: number;
+        repairSuccessRate: number;
+        neutralFallbackRate: number;
+        turnsWithRejectedEffects: number;
+        repairTurnRate: number;
+        linesDelivered: number;
+        fallbackLines: number;
+        fallbackRate: number;
+        linesByRole: Record<string, number>;
+        rejectionsByRole: Record<string, number>;
+        scanned: number;
+        truncated: boolean;
+    };
+    archive: {
+        floor: number;
+        prunedThrough: number;
+    };
+}
+/** A quality suite's report. `notApplicable` metrics are excluded from
+ *  `passRate` — a metric with no data is a finding, not a pass. */
+export interface WorldEvalReport {
+    contractVersion: number;
+    suite: 'drama' | 'npc';
+    worldInstanceId: string;
+    turns: number;
+    metrics: Array<{
+        id: string;
+        label: string;
+        direction: 'higher' | 'lower' | 'exact' | 'band';
+        value: number;
+        threshold: number;
+        thresholdMax?: number;
+        pass: boolean;
+        notApplicable?: boolean;
+        detail: string;
+    }>;
+    passed: number;
+    failed: number;
+    notApplicable: number;
+    passRate: number;
+    ok: boolean;
+}
+/** One row of the operator queue view. No message text, no signing material,
+ *  no payload hash — a queue question, not a transcript. */
+export interface WorldDeliveryOpsRow {
+    deliveryId: string;
+    turnId: string;
+    roleId: string;
+    uid: string;
+    sessionId: string;
+    ledgerSeq?: number;
+    sequence?: number;
+    status: 'pending' | 'delivering' | 'delivered' | 'retry_wait' | 'dead' | 'rehydrating' | 'unrecoverable' | 'resolved_gap';
+    attempts: number;
+    ageMs: number;
+    nextAttemptAt: number;
+    createdAt: number;
+    deliveredAt?: number;
+    lastErrorClass?: string;
+    payloadRedactedAt?: number;
+    requeueCount?: number;
+    rehydratedAt?: number;
+    rehydratedFrom?: 'ledger' | 'archive';
+    unrecoverableReason?: WorldRehydrateFailure;
+    resolvedGapAt?: number;
+    replacesDeliveryId?: string;
+    /** How many times the settled row's atomic cleanup has failed, and when it
+     *  crossed the threshold at which it becomes something to look at. Present
+     *  only once a cleanup has actually failed — an ordinary row omits both.
+     *  They are cleanup bookkeeping, never a delivery status: a row carrying
+     *  them is still `delivered` and still terminal. A persistently non-zero
+     *  `cleanupRetryCount` across a session means its receipt store is refusing
+     *  writes and the receipts are not shrinking. */
+    cleanupRetryCount?: number;
+    cleanupStalledAt?: number;
+    /** This row is the oldest unlanded line of its session AND cannot move — so
+     *  it is why that reader is waiting. */
+    blocking: boolean;
+}
+export interface WorldDeliveryPage {
+    rows: WorldDeliveryOpsRow[];
+    cursor?: string;
+    truncated: boolean;
+    scanned: number;
+}
+export interface WorldDeliveryDetail extends WorldDeliveryOpsRow {
+    channel: string;
+    payloadType: string;
+    /** Only when `includePayload` was passed — and that read was audited. */
+    payload?: {
+        text: string;
+        userText: string;
+    };
+}
+export interface WorldDrainReport {
+    scanned: number;
+    claimed: number;
+    delivered: number;
+    failed: number;
+    dead: number;
+    /** Sessions still owing their oldest line after this pass. */
+    blocked: number;
+    saturated: boolean;
+}
+/** The production hand-off (Batch 7). Every line keeps the origin the SERVER
+ *  verified: `evidence` with the turn it came from, or `suggestion` because
+ *  nothing committed matched it — whatever the model claimed. A suggestion is
+ *  never laundered into a fact downstream. */
+export interface ApprovedScriptExportRow {
+    exportId: string;
+    draftId: string;
+    editorialId: string;
+    worldInstanceId: string;
+    environmentId: string;
+    content: {
+        contractVersion: number;
+        exportId: string;
+        title: string;
+        lineage: Record<string, unknown>;
+        review: {
+            reviewer: string;
+            approvedAt: string;
+            sceneDecisions: Record<string, unknown>;
+        };
+        characters: Array<{
+            roleId: string;
+            storyRoleId?: string;
+            lines: number;
+        }>;
+        scenes: Array<Record<string, unknown>>;
+        stateChanges: Array<{
+            summary: string;
+            sourceTurnId: string;
+        }>;
+        suggestionRatio: number;
+        exportDigest: string;
+    };
+    createdAt: string;
+    createdBy: string;
+    deliveredAt?: string;
+    deliveryAttempted?: number;
+    deliveryOk?: number;
+}
+export interface WorldClientOptions {
+    /** The project this client acts for. */
+    projectId: string;
+    /** An OWNER-plane credential (a signed-in admin's ID token) for the control
+     *  plane: story packages, world definitions, drafts, replay, reads. */
+    adminToken?: string;
+    /** A project Secret Key (`pchy_sk_…`) for the MACHINE lane: world sessions,
+     *  turns and trusted events. It also carries the test/live axis. */
+    secretKey?: string;
+    /** The event-source signing key pair the turns door and `/events` verify.
+     *  `source` must be the world's own `providerRef`. */
+    signing?: {
+        source: string;
+        keyId: string;
+        secret: string;
+    };
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+    /** Per-request timeout. A coordinated turn is a multi-model act — the
+     *  default is generous on purpose, and lower is usually wrong. */
+    timeoutMs?: number;
+}
+export declare class PouchyWorldClient {
+    readonly projectId: string;
+    private readonly baseUrl;
+    private readonly doFetch;
+    private readonly adminToken?;
+    private readonly secretKey?;
+    private readonly signing?;
+    private readonly timeoutMs;
+    constructor(options: WorldClientOptions);
+    listStoryPackages(): Promise<{
+        packages: unknown[];
+    }>;
+    createStoryPackage(content: unknown): Promise<{
+        packageId: string;
+        revision: number;
+        contentHash: string;
+    }>;
+    getStoryPackage(packageId: string): Promise<unknown>;
+    /** Publish the next IMMUTABLE story revision. Idempotent on content: the
+     *  same bytes return the existing revision rather than minting a twin. */
+    publishStoryPackage(packageId: string, content: unknown): Promise<{
+        packageId: string;
+        revision: number;
+        contentHash: string;
+        created: boolean;
+    }>;
+    listWorlds(): Promise<{
+        environments: unknown[];
+    }>;
+    createWorld(definition: unknown): Promise<{
+        environmentId: string;
+        environmentRevision: number;
+        contentHash: string;
+    }>;
+    getWorld(environmentId: string): Promise<unknown>;
+    /** 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
+     *  underneath its players. */
+    publishWorld(environmentId: string, definition: unknown): Promise<{
+        environmentId: string;
+        environmentRevision: number;
+        contentHash: string;
+        created: boolean;
+    }>;
+    getWorldState(environmentId: string, worldInstanceId: string): Promise<{
+        worldInstanceId: string;
+        environmentRevision: number;
+        state: Record<string, unknown>;
+    }>;
+    /** Read back a COMMITTED turn. The recovery path when a response was lost:
+     *  it re-runs nothing, and a 404 means the turn never committed. */
+    getTurn(environmentId: string, worldInstanceId: string, turnId: string): Promise<Record<string, unknown>>;
+    /** Verify that the materialized state is what the committed ledger says.
+     *  Always a dry run — it reports, it never repairs. Pass the previous
+     *  report's `cursor` to continue a run that came back `incomplete`. */
+    replayLedger(environmentId: string, worldInstanceId: string, options?: {
+        cursor?: string;
+        maxEntries?: number;
+    }): Promise<WorldReplayReport>;
+    /** Walk a replay to completion, page by page. Bounded by `maxPages` so a
+     *  caller can never spin: an unfinished walk returns its last report, and
+     *  the cursor is in it. */
+    replayLedgerToEnd(environmentId: string, worldInstanceId: string, options?: {
+        maxPages?: number;
+    }): Promise<WorldReplayReport>;
+    /** The delivery queue for one instance (Batch 7). Statuses, timings, attempt
+     *  counts, error classes, and which row is blocking its session — never the
+     *  message bodies. */
+    listDeliveries(environmentId: string, worldInstanceId: string, filters?: {
+        status?: 'pending' | 'delivering' | 'delivered' | 'retry_wait' | 'dead';
+        sessionId?: string;
+        turnId?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<WorldDeliveryPage>;
+    /** One delivery. `includePayload` returns the line itself and writes an audit
+     *  row naming you — pass it deliberately, not by default. */
+    getDelivery(environmentId: string, worldInstanceId: string, deliveryId: string, options?: {
+        includePayload?: boolean;
+    }): Promise<WorldDeliveryDetail>;
+    /** Run one bounded drain now — for the moment after a requeue. */
+    drainDeliveries(environmentId: string, worldInstanceId: string): Promise<WorldDrainReport>;
+    /** Put a dead letter back in the queue. There is deliberately no payload
+     *  parameter: the beat was committed by the coordinator, and supplying a
+     *  different line here would be authoring world history through the delivery
+     *  plane. Idempotent — an already-queued row is a no-op. */
+    requeueDelivery(environmentId: string, worldInstanceId: string, deliveryId: string): Promise<{
+        ok: boolean;
+        status?: string;
+        reason?: string;
+    }>;
+    /** Turn an APPROVED editorial draft into a versioned production hand-off
+     *  (Batch 7). 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` also sends `world.script_approved` to the project's
+     *  webhooks, carrying lineage and identifiers but never the script body. */
+    createApprovedExport(environmentId: string, worldInstanceId: string, draftId: string, editorialId: string, options?: {
+        notify?: boolean;
+    }): Promise<ApprovedScriptExportRow>;
+    listApprovedExports(environmentId: string, worldInstanceId: string, draftId: string, editorialId: string): Promise<{
+        exports: unknown[];
+    }>;
+    /** The next Story Package as a CANDIDATE — validated, and returned rather
+     *  than published. Publishing it is a separate act by a person, through
+     *  `createStoryPackage`. Only evidence-origin material becomes canon. */
+    deriveStoryPackageCandidate(environmentId: string, worldInstanceId: string, draftId: string, editorialId: string, exportId: string, options?: {
+        name?: string;
+        summary?: string;
+    }): Promise<{
+        exportId: string;
+        status: 'candidate';
+        publishWith: string;
+        droppedSuggestions: number;
+        content: Record<string, unknown>;
+    }>;
+    /** Rebuild a dead letter whose text was redacted, FROM THE RECORD (Batch
+     *  7.1). Takes no body — nobody types a replacement line and no model
+     *  regenerates one. Accepted only if the rebuild re-derives the same delivery
+     *  id and the same content digest captured before the text was destroyed;
+     *  otherwise it refuses with a code and the row becomes `unrecoverable`,
+     *  which still blocks the session. */
+    rehydrateDelivery(environmentId: string, worldInstanceId: string, deliveryId: string): Promise<{
+        ok: boolean;
+        status?: string;
+        from?: 'ledger' | 'archive';
+        error?: WorldRehydrateFailure;
+    }>;
+    /** Account for a beat that cannot be recovered. The only exit from
+     *  `unrecoverable`, and it takes NO text: the notice is generated
+     *  server-side from a fixed catalogue and rendered in the reader's language.
+     *  The original resolves when the notice LANDS, not when you call this. */
+    resolveDeliveryGap(environmentId: string, worldInstanceId: string, deliveryId: string): Promise<{
+        ok: boolean;
+        noticeDeliveryId?: string;
+        created?: boolean;
+        noticeKey?: string;
+    }>;
+    /** Operator metrics for one instance (Batch 6): delivery and turn families,
+     *  kept apart because "the lines arrived" and "the world played well" are
+     *  different questions. */
+    getWorldMetrics(environmentId: string, worldInstanceId: string): Promise<WorldInstanceMetrics>;
+    /** Score the committed history against a quality suite. Deterministic — no
+     *  model judges the output, so a score is something you can regress. */
+    evaluateWorld(environmentId: string, worldInstanceId: string, options?: {
+        suite?: 'drama' | 'npc';
+        replayVerdict?: string;
+    }): Promise<WorldEvalReport>;
+    /** Ledger archival. The default action is `plan`, which writes nothing;
+     *  `execute` copies and never deletes; `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. */
+    archiveLedger(environmentId: string, worldInstanceId: string, options?: {
+        action?: 'plan' | 'execute' | 'verify' | 'prune';
+        confirm?: boolean;
+    }): Promise<Record<string, unknown>>;
+    listScriptDrafts(environmentId: string, worldInstanceId: string): Promise<{
+        drafts: unknown[];
+    }>;
+    /** 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: 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. */
+    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. */
+    exportScriptDraft(environmentId: string, worldInstanceId: string, draftId: string): Promise<Record<string, unknown>>;
+    /** 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: string, worldInstanceId: string, draftId: string): Promise<{
+        editorials: unknown[];
+    }>;
+    /** Generate (or return) an editorial reading. Idempotent per model + prompt
+     *  version + input digest, so asking twice is not a second opinion. */
+    createEditorialDraft(environmentId: string, worldInstanceId: string, draftId: string, model?: string): Promise<EditorialDraftRow>;
+    getEditorialDraft(environmentId: string, worldInstanceId: string, draftId: string, editorialId: string): Promise<EditorialDraftRow>;
+    /** Move an editorial draft through its review lifecycle. `exported` is not
+     *  settable here — `exportEditorialDraft` writes it. */
+    setEditorialStatus(environmentId: string, worldInstanceId: string, draftId: string, editorialId: string, status: 'under_review' | 'changes_requested' | 'approved' | 'rejected', note?: string): Promise<EditorialDraftRow>;
+    /** One human verdict on one scene. `edited` carries the editor's own text —
+     *  the only way text in this layer changes after generation. */
+    decideEditorialScene(environmentId: string, worldInstanceId: string, draftId: string, editorialId: string, input: {
+        sceneId: string;
+        decision: 'accepted' | 'edited' | 'rejected';
+        editedText?: string;
+        note?: string;
+    }): Promise<EditorialDraftRow>;
+    /** Export an APPROVED editorial draft. `preview: true` reads the same payload
+     *  without stamping it exported, so a reviewer can see what would leave. */
+    exportEditorialDraft(environmentId: string, worldInstanceId: string, draftId: string, editorialId: string, options?: {
+        preview?: boolean;
+    }): Promise<Record<string, unknown>>;
+    /** Mint a world SESSION for one end user in one role. The returned token is
+     *  what your own frontend uses with the companion SDK; it is scoped to that
+     *  instance and role and carries no project credential. */
+    createWorldSession(input: {
+        environment: string;
+        role: string;
+        externalUserId: string;
+        worldInstance?: string;
+        requestId?: string;
+    }): Promise<Record<string, unknown>>;
+    /** 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: {
+        environmentId: string;
+        worldInstanceId: string;
+        turnId?: string;
+        text: string;
+        sourceRoleId?: string;
+        traceId?: string;
+    }): Promise<WorldTurnResult>;
+    /** Send a trusted EVENT into a world. On a `coordinated` world this becomes
+     *  one coordinator turn; on an `actor` world it wakes each subscribed role.
+     *  Either way `eventId` is the dedupe key — re-send it freely. */
+    sendEvent(input: {
+        name: string;
+        eventId?: string;
+        environment: string;
+        worldInstance: string;
+        data: Record<string, unknown>;
+        schemaVersion?: number;
+        occurredAt?: number;
+    }): Promise<Record<string, unknown>>;
+    private owner;
+    /** 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;
+    private request;
+}