@pome-sh/cli 0.1.0

package/node_modules/@pome-sh/sdk/dist/errors.js

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Generic SDK error envelope. Twin authors can throw `TwinError` from
+// handlers to surface a non-200 response with a custom message; the
+// recorder middleware unwraps it into the standard envelope and records
+// the error string per recording-spec.md v1.0.
+import { z } from "zod";
+export class TwinError extends Error {
+    status;
+    errors;
+    constructor(message, status, errors) {
+        super(message);
+        this.status = status;
+        this.errors = errors;
+        this.name = "TwinError";
+    }
+}
+/**
+ * Thrown by the SDK's tool dispatch routes (`/mcp/call`,
+ * `/mcp/tools/:name`, JSON-RPC `tools/call`) when the named tool is not in
+ * the registry. A distinct class so a twin's `errorEnvelope` hook can shape
+ * the frozen per-twin wire format (slack 404 `unknown_tool`, stripe 400
+ * `tool_unknown`, …) without string-matching messages.
+ */
+export class UnknownToolError extends TwinError {
+    tool;
+    constructor(tool, status = 404) {
+        super(`Unknown tool: ${tool}`, status);
+        this.tool = tool;
+        this.name = "UnknownToolError";
+    }
+}
+export function envelopeFor(error) {
+    if (error instanceof TwinError) {
+        return {
+            status: error.status,
+            body: { message: error.message, ...(error.errors ? { errors: error.errors } : {}) },
+        };
+    }
+    if (error instanceof z.ZodError) {
+        return {
+            status: 422,
+            body: {
+                message: "Validation Failed",
+                errors: error.issues.map((issue) => ({
+                    field: issue.path.join("."),
+                    code: issue.code,
+                    message: issue.message,
+                })),
+            },
+        };
+    }
+    if (error instanceof SyntaxError) {
+        return { status: 400, body: { message: "Problems parsing JSON" } };
+    }
+    return {
+        status: 500,
+        body: { message: error instanceof Error ? error.message : "Internal Server Error" },
+    };
+}
+//# sourceMappingURL=errors.js.map

package/node_modules/@pome-sh/sdk/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,wEAAwE;AACxE,+CAA+C;AAE/C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,OAAO,SAAU,SAAQ,KAAK;IAGvB;IACA;IAHX,YACE,OAAe,EACN,MAAc,EACd,MAAkB;QAE3B,KAAK,CAAC,OAAO,CAAC,CAAC;QAHN,WAAM,GAAN,MAAM,CAAQ;QACd,WAAM,GAAN,MAAM,CAAY;QAG3B,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,gBAAiB,SAAQ,SAAS;IACxB;IAArB,YAAqB,IAAY,EAAE,MAAM,GAAG,GAAG;QAC7C,KAAK,CAAC,iBAAiB,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC;QADpB,SAAI,GAAJ,IAAI,CAAQ;QAE/B,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAOD,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,KAAK,YAAY,SAAS,EAAE,CAAC;QAC/B,OAAO;YACL,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,IAAI,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;SACpF,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,YAAY,CAAC,CAAC,QAAQ,EAAE,CAAC;QAChC,OAAO;YACL,MAAM,EAAE,GAAG;YACX,IAAI,EAAE;gBACJ,OAAO,EAAE,mBAAmB;gBAC5B,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;oBACnC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;oBAC3B,IAAI,EAAE,KAAK,CAAC,IAAI;oBAChB,OAAO,EAAE,KAAK,CAAC,OAAO;iBACvB,CAAC,CAAC;aACJ;SACF,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;QACjC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,uBAAuB,EAAE,EAAE,CAAC;IACrE,CAAC;IACD,OAAO;QACL,MAAM,EAAE,GAAG;QACX,IAAI,EAAE,EAAE,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,uBAAuB,EAAE;KACpF,CAAC;AACJ,CAAC"}

package/node_modules/@pome-sh/sdk/dist/failure-injection.d.ts

@@ -0,0 +1,43 @@
+import type { MiddlewareHandler } from "hono";
+import { z } from "zod";
+import type { RecorderEvent } from "@pome-sh/shared-types";
+export declare const FAILURE_INJECTION_OVERRIDE_KEY = "failureInjectionOverride";
+export type FailureInjectionOverride = {
+    status: number;
+    body: unknown;
+};
+export type FailureInjectionMode = "before_handler" | "after_handler";
+export type FailureInjectionRule = {
+    method: string;
+    path: string;
+    attempt: number;
+    mode: FailureInjectionMode;
+    status: number;
+    body: unknown;
+};
+export declare const failureInjectionRuleSchema: z.ZodObject<{
+    method: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    path: z.ZodString;
+    attempt: z.ZodNumber;
+    mode: z.ZodDefault<z.ZodEnum<{
+        before_handler: "before_handler";
+        after_handler: "after_handler";
+    }>>;
+    status: z.ZodNumber;
+    body: z.ZodUnknown;
+}, z.core.$strip>;
+export type FailureInjectionStore = {
+    setRules(rules: FailureInjectionRule[]): void;
+    clear(): void;
+    matchAndConsume(accountId: string, method: string, path: string): FailureInjectionRule | null;
+};
+export declare function createFailureInjectionStore(): FailureInjectionStore;
+export interface FailureInjectionMiddlewareOptions {
+    /** Sink for before_handler events. Optional — a recorderless app still injects. */
+    recorder?: {
+        record(event: RecorderEvent): void;
+    };
+    runId: string;
+    twin: string;
+}
+export declare function failureInjectionMiddleware(store: FailureInjectionStore, options: FailureInjectionMiddlewareOptions): MiddlewareHandler;

package/node_modules/@pome-sh/sdk/dist/failure-injection.js

@@ -0,0 +1,160 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Scenario-level failure injection (FDRS-339), graduated from twin-stripe
+// into the engine by the F-684 port ruling: making a twin fail on attempt N
+// of a (method, path) tuple is a generic twin capability — any provider
+// double needs "the server processed it but the client never saw the
+// response" to reproduce lost-response retry bugs. Only the rule *payloads*
+// (status + error envelope) are twin-domain; they ride in via the seed.
+//
+// Two modes:
+//
+//   - `before_handler` → the matched request never reaches the route
+//     handler; the middleware returns the configured envelope directly and
+//     records a `state_mutation: false`, `state_delta: null` event.
+//   - `after_handler` → the handler is invoked normally (state mutation
+//     and `state_delta` capture proceed). The middleware parks the override
+//     on the context under `FAILURE_INJECTION_OVERRIDE_KEY`; the twin's
+//     response path substitutes status + body on the way out, so the
+//     recorded event and the wire agree. This models a "server processed
+//     but response delivery failed" failure — required to reproduce the
+//     FDRS-316 hero scenario.
+//
+// Counters live per `(account_id, method, path)` so successive POSTs from
+// the same account to the same path resolve to `attempt: 1`, `attempt: 2`,
+// …, deterministically. Other routes don't influence the counter — only
+// requests to a tuple that has at least one registered rule are counted.
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+export const FAILURE_INJECTION_OVERRIDE_KEY = "failureInjectionOverride";
+export const failureInjectionRuleSchema = z.object({
+    method: z.string().min(1).transform((s) => s.toUpperCase()),
+    path: z.string().min(1),
+    attempt: z.number().int().positive(),
+    mode: z
+        .enum(["before_handler", "after_handler"])
+        .default("after_handler"),
+    status: z.number().int().min(100).max(599),
+    body: z.unknown(),
+});
+export function createFailureInjectionStore() {
+    // The store is intentionally global across accounts. The (account_id,
+    // method, path) counter keys keep accounts independent for matching;
+    // rules themselves apply to whichever account issues the matching
+    // request. Single-account scenarios (the common case, including the
+    // FDRS-316 hero) don't need to express scope per rule.
+    let rules = [];
+    const counters = new Map();
+    const tuplesWithRules = new Set();
+    function tupleKey(method, path) {
+        return `${method.toUpperCase()}\0${path}`;
+    }
+    function counterKey(accountId, method, path) {
+        return `${accountId}\0${method.toUpperCase()}\0${path}`;
+    }
+    function rebuildIndex() {
+        tuplesWithRules.clear();
+        for (const r of rules)
+            tuplesWithRules.add(tupleKey(r.method, r.path));
+    }
+    return {
+        setRules(next) {
+            rules = next.slice();
+            counters.clear();
+            rebuildIndex();
+        },
+        clear() {
+            rules = [];
+            counters.clear();
+            tuplesWithRules.clear();
+        },
+        matchAndConsume(accountId, method, path) {
+            const tk = tupleKey(method, path);
+            if (!tuplesWithRules.has(tk))
+                return null;
+            const ck = counterKey(accountId, method, path);
+            const count = (counters.get(ck) ?? 0) + 1;
+            counters.set(ck, count);
+            return (rules.find((r) => r.method.toUpperCase() === method.toUpperCase() &&
+                r.path === path &&
+                r.attempt === count) ?? null);
+        },
+    };
+}
+export function failureInjectionMiddleware(store, options) {
+    return async (c, next) => {
+        const session = c.get("session");
+        // Auth runs first; if it failed there's no session and we shouldn't
+        // shadow that with a manufactured failure.
+        if (!session) {
+            await next();
+            return;
+        }
+        const accountId = typeof session.account_id === "string" ? session.account_id : String(session.sid ?? "_anon");
+        const method = c.req.method.toUpperCase();
+        const rawPath = new URL(c.req.url).pathname;
+        // Rules are written against the canonical provider path
+        // (e.g., "/v1/refunds"). Strip the session prefix when present so
+        // path-mounted (`/s/:sid/v1/refunds`) and root-mounted (`/v1/refunds`,
+        // stripe F3 SDK compat) requests both match.
+        const path = stripSessionPrefix(rawPath);
+        const rule = store.matchAndConsume(accountId, method, path);
+        if (!rule) {
+            await next();
+            return;
+        }
+        if (rule.mode === "before_handler") {
+            const started = Date.now();
+            let requestBody = null;
+            try {
+                requestBody = await c.req.raw.clone().text();
+            }
+            catch {
+                requestBody = null;
+            }
+            const requestId = `req_${randomUUID()}`;
+            const stepId = c.req.header("x-pome-scenario-step-id") ?? null;
+            options.recorder?.record({
+                ts: new Date().toISOString(),
+                run_id: options.runId,
+                twin: options.twin,
+                request_id: requestId,
+                correlation_id: c.req.header("x-pome-correlation-id") ?? requestId,
+                task_step_id: stepId,
+                scenario_step_id: stepId,
+                step_id: null,
+                tool_call_id: null,
+                method,
+                path: rawPath,
+                request_body: requestBody,
+                status: rule.status,
+                response_body: rule.body,
+                latency_ms: Date.now() - started,
+                fidelity: "semantic",
+                state_mutation: false,
+                state_delta: null,
+                error: rule.status >= 400 ? errorMessage(rule.body) : null,
+            });
+            return c.json(rule.body, rule.status);
+        }
+        // after_handler: let the handler run, but stash the override so the
+        // twin's response path can substitute status + body on the way out.
+        // state_mutation + state_delta keep the real-handler truth.
+        const override = { status: rule.status, body: rule.body };
+        c.set(FAILURE_INJECTION_OVERRIDE_KEY, override);
+        await next();
+    };
+}
+function stripSessionPrefix(path) {
+    const match = path.match(/^\/s\/[^/]+(\/.*)$/);
+    return match?.[1] ?? path;
+}
+function errorMessage(body) {
+    if (body && typeof body === "object" && "error" in body) {
+        const err = body.error;
+        if (err && typeof err.message === "string")
+            return err.message;
+    }
+    return "request failed";
+}
+//# sourceMappingURL=failure-injection.js.map

package/node_modules/@pome-sh/sdk/dist/failure-injection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-injection.js","sourceRoot":"","sources":["../src/failure-injection.ts"],"names":[],"mappings":"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"}

package/node_modules/@pome-sh/sdk/dist/fidelity.d.ts

@@ -0,0 +1,8 @@
+import type { TwinDefinition } from "./index.js";
+export interface EmitFidelityOptions {
+    /** ISO date (YYYY-MM-DD) embedded in "Last verified". Defaults to today. */
+    lastVerified?: string;
+    /** Optional trailing notes section appended after the table. */
+    notes?: string;
+}
+export declare function emitFidelityMarkdown<TDb, TSeed, TDomain>(definition: TwinDefinition<TDb, TSeed, TDomain>, options?: EmitFidelityOptions): string;

package/node_modules/@pome-sh/sdk/dist/fidelity.js

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// FIDELITY.md emitter. Generates the Tools × Tier × Backing surface × Tests
+// × Deviations table from a `TwinDefinition`. Per-tool fidelity metadata
+// lives on `ToolSpec.fidelity` (optional); when missing, the row falls back
+// to the manifest's `fidelity.default` tier and em-dash placeholders.
+export function emitFidelityMarkdown(definition, options = {}) {
+    const lastVerified = options.lastVerified ?? new Date().toISOString().slice(0, 10);
+    const lines = [];
+    lines.push(`# ${definition.id} Twin Fidelity`);
+    lines.push("");
+    lines.push(`Auto-generated by \`@pome-sh/sdk\` for twin \`${definition.id}\` v${definition.version}.`);
+    lines.push("");
+    lines.push(`Last verified: ${lastVerified}.`);
+    lines.push("");
+    lines.push("## MCP Tools");
+    lines.push("");
+    lines.push("| Tool | Backing surface | Tier | Tests | Known deviations |");
+    lines.push("| --- | --- | --- | --- | --- |");
+    for (const tool of definition.tools) {
+        const fid = tool.fidelity ?? {};
+        const tier = fid.tier ?? definition.fidelity.default;
+        const surface = fid.backingSurface ?? "—";
+        const tests = (fid.tests ?? []).length
+            ? (fid.tests ?? []).map((t) => `\`${t}\``).join(", ")
+            : "—";
+        const deviations = (fid.deviations ?? "—").replace(/\r?\n/g, " ");
+        lines.push(`| \`${tool.name}\` | ${surface} | ${tier} | ${tests} | ${deviations} |`);
+    }
+    if (options.notes) {
+        lines.push("");
+        lines.push("## Notes");
+        lines.push("");
+        lines.push(options.notes);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+//# sourceMappingURL=fidelity.js.map

package/node_modules/@pome-sh/sdk/dist/fidelity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fidelity.js","sourceRoot":"","sources":["../src/fidelity.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,EAAE;AACF,4EAA4E;AAC5E,yEAAyE;AACzE,4EAA4E;AAC5E,sEAAsE;AAWtE,MAAM,UAAU,oBAAoB,CAClC,UAA+C,EAC/C,UAA+B,EAAE;IAEjC,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACnF,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,CAAC,IAAI,CAAC,KAAK,UAAU,CAAC,EAAE,gBAAgB,CAAC,CAAC;IAC/C,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CACR,iDAAiD,UAAU,CAAC,EAAE,OAAO,UAAU,CAAC,OAAO,GAAG,CAC3F,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,kBAAkB,YAAY,GAAG,CAAC,CAAC;IAC9C,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,8DAA8D,CAAC,CAAC;IAC3E,KAAK,CAAC,IAAI,CAAC,iCAAiC,CAAC,CAAC;IAE9C,KAAK,MAAM,IAAI,IAAI,UAAU,CAAC,KAAK,EAAE,CAAC;QACpC,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,IAAI,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC;QACrD,MAAM,OAAO,GAAG,GAAG,CAAC,cAAc,IAAI,GAAG,CAAC;QAC1C,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM;YACpC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;YACrD,CAAC,CAAC,GAAG,CAAC;QACR,MAAM,UAAU,GAAG,CAAC,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QAClE,KAAK,CAAC,IAAI,CACR,OAAO,IAAI,CAAC,IAAI,QAAQ,OAAO,MAAM,IAAI,MAAM,KAAK,MAAM,UAAU,IAAI,CACzE,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACvB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/node_modules/@pome-sh/sdk/dist/index.d.ts

@@ -0,0 +1,335 @@
+import { z } from "zod";
+import type { Context, Hono } from "hono";
+import { recorderEventSchema, recorderFidelitySchema, type RecorderEvent, type RecorderFidelity, type TwinId } from "@pome-sh/shared-types";
+export { recorderEventSchema, recorderFidelitySchema };
+export type { RecorderEvent, RecorderFidelity, TwinId };
+export { openTwinDatabase } from "./db.js";
+export type { OpenTwinDatabaseOptions, TwinDatabase, TwinRunResult, TwinStatement, TwinTransaction } from "./db.js";
+export { redactEvent, redactSecrets } from "./redaction.js";
+export declare const fidelityTierSchema: z.ZodEnum<{
+    semantic: "semantic";
+    unsupported: "unsupported";
+    shape: "shape";
+}>;
+export type FidelityTier = z.infer<typeof fidelityTierSchema>;
+export interface ToolFidelityMetadata {
+    tier?: FidelityTier;
+    backingSurface?: string;
+    tests?: string[];
+    deviations?: string;
+}
+/**
+ * Per-call context handed to tool handlers by every MCP dispatch surface
+ * (JSON-RPC `tools/call`, legacy `/mcp/tools/:name` + `/mcp/call`). Carries
+ * the authenticated session (actor identity) and a `reportDelta` sink so
+ * MCP-dispatched mutations surface `state_delta` on the recorded event —
+ * the two facilities the per-twin mcp.ts modules had before F-683.
+ */
+export interface ToolCallContext {
+    /** The session set by the engine's bearerAuth for this request. */
+    session?: import("./auth.js").SessionValue;
+    /** Report the row-level before/after recorded as this event's `state_delta`. */
+    reportDelta: (delta: RecorderEvent["state_delta"]) => void;
+}
+export interface ToolSpec<TDomain = unknown, TInput = unknown, TOutput = unknown> {
+    name: string;
+    description: string;
+    schema: z.ZodType<TInput>;
+    handler: (domain: TDomain, args: TInput, ctx: ToolCallContext) => TOutput | Promise<TOutput>;
+    mutation: boolean;
+    fidelity?: ToolFidelityMetadata;
+    /**
+     * MCP tool-list annotations (e.g. `{ readOnlyHint: true }`), emitted
+     * verbatim on both tool-list surfaces when present.
+     */
+    annotations?: Record<string, unknown>;
+    /**
+     * Literal JSON-Schema override for the tool listings. Twins with a frozen
+     * schema wire shape (e.g. slack's forced draft-7
+     * `additionalProperties:false` form) supply it here; defaults to
+     * `z.toJSONSchema(schema)`.
+     */
+    inputSchema?: Record<string, unknown>;
+}
+/** The JSON-Schema a tool advertises: the declared override, else zod-derived. */
+export declare function toolInputSchema(tool: Pick<ToolSpec, "schema" | "inputSchema">): Record<string, unknown>;
+export interface TwinFidelity {
+    default: FidelityTier;
+}
+export interface RouteContext<TDomain = unknown> {
+    domain: TDomain;
+    recorder: RecorderHandle;
+    runId: string;
+    twin: TwinId;
+}
+export type RouteRegistrar<TDomain = unknown> = (app: Hono, ctx: RouteContext<TDomain>) => void;
+export interface RecorderHandlerResult {
+    status: number;
+    body: unknown;
+    /**
+     * Optional override for the per-event `state_mutation` field. When unset,
+     * the recorder uses the `mutation` flag passed to `handle({mutation})`.
+     * Used by the SDK's MCP dispatch routes to plumb the per-tool mutation
+     * flag (different per call) into the recorder event.
+     */
+    mutation?: boolean;
+    /**
+     * Optional state delta recorded on the event (`state_delta`). Routes that
+     * know exactly what they changed surface it here; defaults to null.
+     */
+    delta?: RecorderEvent["state_delta"];
+}
+export interface RecorderHandle {
+    record(event: RecorderEvent): void;
+    events(): RecorderEvent[];
+    /** Event count without the O(N) copy `events()` makes. */
+    count(): number;
+    /** Events dropped by a bounded store (0 for the default unbounded store). */
+    dropped(): number;
+    /**
+     * Durability barrier (F-720). Forwards to the backing `RecorderStore.flush`
+     * when present. Await before upload/finalize when using a durable store.
+     */
+    flush(): Promise<void>;
+    /**
+     * Flush + release the backing store (F-720). Idempotent.
+     */
+    close(): Promise<void>;
+    /**
+     * Wrap a Hono handler with auto-recording. The wrapped function returns
+     * `{ status, body }` (not a `Response`); the recorder fills in `ts`,
+     * `request_id`, `latency_ms`, `state_mutation`, `error`, then writes the
+     * `RecorderEvent` and returns `c.json(body, status)`.
+     */
+    handle(opts: {
+        mutation: boolean;
+        fidelity?: RecorderFidelity;
+        /** Per-surface error projection override (admin routes have their own frozen envelope on some twins). */
+        errorEnvelope?: (err: unknown) => {
+            status: number;
+            body: unknown;
+        };
+    }, fn: (c: Context) => Promise<RecorderHandlerResult> | RecorderHandlerResult): (c: Context) => Promise<Response>;
+}
+export interface AdminHandlers<TDomain = unknown, TSeed = unknown> {
+    /**
+     * Implements POST /admin/reset. `reportDelta` records the row-level
+     * before/after as the admin event's `state_delta` (github's frozen tape
+     * records the seed delta on admin mutations, F-682).
+     */
+    reset?: (ctx: {
+        domain: TDomain;
+        reportDelta: (delta: RecorderEvent["state_delta"]) => void;
+    }) => unknown | Promise<unknown>;
+    /**
+     * Implements POST /admin/seed. The seed body is Zod-parsed via
+     * `definition.seed` first; `reportDelta` stamps the event's `state_delta`.
+     */
+    seed?: (ctx: {
+        domain: TDomain;
+        seed: TSeed;
+        reportDelta: (delta: RecorderEvent["state_delta"]) => void;
+    }) => unknown | Promise<unknown>;
+    /**
+     * Whether /admin/reset|seed land on the recorder tape. Default true
+     * (github/slack frozen tapes record admin events); stripe pins false —
+     * its pre-port recorder never saw admin traffic.
+     */
+    recorded?: boolean;
+    /**
+     * Per-surface error projection for /admin/reset|seed. Pre-port slack's
+     * admin handlers answered EVERY thrown error with 500
+     * {ok:false, error:"internal_error", warning} — bypassing the session
+     * envelope. Defaults to the twin's `errorEnvelope`.
+     */
+    errorEnvelope?: (err: unknown) => {
+        status: number;
+        body: unknown;
+    };
+    /**
+     * The twin's admin-gate 403 envelope (slack pins
+     * `{ok:false, error:"restricted_action"}`). Gate mechanism —
+     * TWIN_ADMIN_TOKEN mode, loopback socket check — stays in the engine
+     * (`packages/sdk/src/admin-gate.ts`); this is pure shape. Defaults to the
+     * generic `{message: "Forbidden"}` envelope.
+     */
+    forbidden?: () => {
+        status: number;
+        body: unknown;
+    };
+}
+export interface TwinDefinition<TDb = unknown, TSeed = unknown, TDomain = unknown> {
+    id: string;
+    version: string;
+    fidelity: TwinFidelity;
+    seed?: z.ZodType<TSeed>;
+    domain: (ctx: {
+        db: TDb;
+        seed: TSeed | undefined;
+    }) => TDomain;
+    routes?: RouteRegistrar<TDomain>;
+    tools: ToolSpec<TDomain>[];
+    /**
+     * Optional state introspection for `GET /s/:sid/_pome/state`. If absent,
+     * the route returns a 501 envelope so consumers fail loudly instead of
+     * silently reading an empty state. `session` is the bearer-resolved
+     * session for the request, so account-scoped twins (stripe) can export
+     * only the calling session's slice (F-684).
+     */
+    state?: (ctx: {
+        domain: TDomain;
+        session?: import("./auth.js").SessionValue;
+    }) => unknown | Promise<unknown>;
+    /**
+     * Optional admin handlers for `/admin/reset` and `/admin/seed`. If absent,
+     * the routes still mount (with the localhost guard) and return a 501
+     * envelope explaining that the twin did not configure them.
+     */
+    admin?: AdminHandlers<TDomain, TSeed>;
+    /**
+     * Optional error-envelope projector. Called from the recorder middleware
+     * catch path to convert a thrown error into the `{ status, body }` shape
+     * the route returns. API-mirroring twins use this to preserve the
+     * upstream API's error shape (e.g. Stripe's nested `{ error: { type,
+     * code, message, doc_url } }`, GitHub's `{ message, documentation_url,
+     * status, errors[] }`). Defaults to a generic `{ message, errors? }`
+     * envelope.
+     */
+    errorEnvelope?: (err: unknown) => {
+        status: number;
+        body: unknown;
+    };
+    /**
+     * `/healthz` `implementation` field (runtime contract). Defaults to
+     * `"<id>_clone"`.
+     */
+    implementation?: string;
+    /**
+     * npm package name reported in the `/healthz` `runtime` block. Defaults
+     * to `"@pome-sh/twin-<id>"`.
+     */
+    packageName?: string;
+    /**
+     * Extra `/healthz` fields merged over the contract core
+     * `{ok, twin, implementation, tools, runtime}`. When absent the engine
+     * adds `{version, fidelity}`; a twin with a frozen healthz shape supplies
+     * its own extras (possibly `{}` to omit both).
+     */
+    healthz?: () => Record<string, unknown>;
+    /**
+     * The twin's 501 loud-unsupported envelope for unknown session routes.
+     * Defaults to the generic `{message, fidelity, method, path}` body.
+     */
+    unsupported?: (ctx: {
+        method: string;
+        path: string;
+    }) => {
+        status: number;
+        body: unknown;
+    };
+    /**
+     * Per-twin request-body reader for the engine-owned JSON surfaces
+     * (`/admin/seed`, legacy `/mcp/call`, `/mcp/tools/:name`). Defaults to
+     * strict JSON — malformed bodies throw `SyntaxError` into the twin's
+     * `errorEnvelope`. Twins with frozen tolerant/form parsing pass their
+     * pre-port reader (slack `parseFormOrJson`, stripe form-or-JSON).
+     */
+    bodyReader?: (c: import("hono").Context) => Promise<unknown>;
+    /**
+     * Session-wide middleware slot mounted immediately after bearer auth and
+     * BEFORE the engine's MCP / `/_pome/*` routes — the pre-port
+     * `session.use("*")` position (stripe registers failure-injection and
+     * idempotency here so they cover MCP dispatch too). Register `use()`
+     * middleware only; routes belong in `routes`.
+     */
+    middleware?: RouteRegistrar<TDomain>;
+    /**
+     * Legacy `POST /mcp/call` dispatch pins (F-683 review): slack's frozen
+     * surface accepts `{name}`/`{params}` as aliases of `{tool}`/`{arguments}`
+     * and answers a body naming no tool with its own envelope instead of the
+     * strict-parse error.
+     */
+    legacyMcp?: {
+        aliases?: boolean;
+        missingTool?: () => {
+            status: number;
+            body: unknown;
+        };
+    };
+    /**
+     * Extra `/s/:sid/_pome/health` fields merged over the contract core
+     * `{ok, twin}`. When absent the engine adds `{version, fidelity}`; a twin
+     * with a frozen per-session health shape (slack: bare {ok, twin};
+     * github: implementation, fidelity, runtime — no version) supplies its
+     * own extras. The hook receives the app's recorder so counters can be
+     * surfaced (stripe).
+     */
+    pomeHealth?: (ctx: {
+        recorder: RecorderHandle;
+    }) => Record<string, unknown>;
+    /**
+     * Extra per-twin GET routes under the reserved `/s/:sid/_pome/*` session
+     * namespace, keyed by subpath (github's frozen
+     * `GET /s/:sid/_pome/access-control`). Handlers return the JSON body;
+     * the engine mounts them behind bearer auth, after its own core routes.
+     * The core names (`health`, `state`, `events`) stay engine-owned — a twin
+     * declaring one refuses to boot.
+     */
+    pomeRoutes?: Record<string, (ctx: {
+        domain: TDomain;
+    }) => unknown | Promise<unknown>>;
+    /**
+     * FDRS-402 adapter-rich stamping pin: when true, every recorded event
+     * persists the incoming `x-pome-correlation-id` header as `tool_call_id`
+     * (github's frozen tape shape). Defaults to false — slack's frozen tape
+     * stamps null. Flipping a twin is a deliberate tape-shape change.
+     */
+    stampToolCallId?: boolean;
+    /**
+     * JSON-RPC `tools/call` unknown-tool result body (frozen per-twin wire
+     * shape). Defaults to the twin's `errorEnvelope` projection of
+     * `UnknownToolError` (slack/stripe). github pins the pre-port
+     * `{message: "Unknown tool: <name>"}` text — its legacy `/mcp/call`
+     * surface keeps the 422 validation envelope from `errorEnvelope`.
+     */
+    mcpUnknownTool?: (name: string) => unknown;
+    /**
+     * Whether the engine mounts `GET /s/:sid/healthz` (200 `{ok, sid}`).
+     * Default true. Stripe pins false — its frozen contract has NO
+     * per-session healthz; the path falls to the 501 catch-all. Flipping a
+     * twin is a contract change (CONTRACT.md + suite in one PR).
+     */
+    sessionHealthz?: boolean;
+    /**
+     * Also mount the session router at the root path. Stripe's frozen F3
+     * SDK-compat surface: real `stripe-node`/`stripe-python` build URLs like
+     * `/v1/payment_intents` with no way to inject a `/s/:sid` prefix, so the
+     * bearer alone resolves the session (pair with `auth.requirePathSid:
+     * false`). Root `/healthz` and `/admin/*` are registered first and stay
+     * first-match. Default false.
+     */
+    mountSessionAtRoot?: boolean;
+    /**
+     * Per-twin auth declarations (F-712): token shape, error envelopes, extra
+     * token locations, raw-bearer / sid-mismatch pins, credential lookup.
+     * Mechanism lives in the engine's `bearerAuth`; this is pure shape.
+     */
+    auth?: import("./auth.js").BearerAuthOptions;
+}
+export declare class TwinManifestError extends Error {
+    readonly issues: ReadonlyArray<z.core.$ZodIssue>;
+    constructor(message: string, issues?: ReadonlyArray<z.core.$ZodIssue>);
+}
+/**
+ * Define a twin manifest. Runs Zod meta-validation at the call site
+ * (typically module-load time) and throws `TwinManifestError` on shape
+ * violations or duplicate tool names.
+ */
+export declare function defineTwin<TDb = unknown, TSeed = unknown, TDomain = unknown>(spec: TwinDefinition<TDb, TSeed, TDomain>): TwinDefinition<TDb, TSeed, TDomain>;
+/**
+ * Path prefixes the SDK reserves under `/s/:sid`. User routes that match or
+ * start with these are rejected at boot per OQ-B6 (`/_pome/*` shadow
+ * detection). `/mcp/*` is reserved for the same reason — community twins
+ * cannot silently override the MCP dispatch surface.
+ */
+export declare const RESERVED_SESSION_PREFIXES: readonly ["/_pome", "/mcp"];