@pome-sh/cli 0.3.0 → 0.4.0

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

@@ -0,0 +1,204 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Structured fidelity inventory (F-730). Each twin ships a machine-readable
+// surface list — `fidelity.inventory.json` — carrying, per MCP tool and REST
+// surface, the heat tier (how deep the endpoint SHOULD be, ruled by the
+// F-729 rubric) orthogonal to the fidelity tier (how deep it IS, per
+// `fidelityTierSchema`), plus a justification for the classification.
+//
+// The FIDELITY doc tables are 1:1-linted against this inventory instead of
+// the old soft "docs mention the tool name" checks (which let twin-stripe's
+// implemented-but-undocumented refunds drift by silently). Known, ticketed
+// doc gaps are declared in `doc_drift`: the lint accepts exactly those
+// gaps and fails loudly once the docs catch up, so a declaration can never
+// outlive the drift it describes.
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+import { fidelityTierSchema } from "./index.js";
+export const heatTierSchema = z.enum(["hot", "warm", "cold", "unclassified"]);
+export const fidelitySurfaceSchema = z.strictObject({
+    /** MCP tool name, or the REST surface string exactly as documented. */
+    name: z.string().min(1),
+    heat: heatTierSchema,
+    fidelity: fidelityTierSchema,
+    justification: z.string().min(1),
+});
+export const fidelityDocDriftSchema = z.strictObject({
+    kind: z.enum(["tool", "rest"]),
+    /** Must match an inventory entry of the same kind. */
+    name: z.string().min(1),
+    reason: z.string().min(1),
+    /** The Linear ticket that owns reconciling the docs. */
+    ticket: z.string().regex(/^F-\d+$/),
+});
+export const fidelityInventorySchema = z.strictObject({
+    twin: z.string().min(1),
+    package: z.string().min(1),
+    /** ISO date (YYYY-MM-DD) of the last human review of this inventory. */
+    updated: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+    notes: z.string().optional(),
+    tools: z.array(fidelitySurfaceSchema).min(1),
+    rest: z.array(fidelitySurfaceSchema),
+    doc_drift: z.array(fidelityDocDriftSchema).default([]),
+});
+export function loadFidelityInventory(path) {
+    return fidelityInventorySchema.parse(JSON.parse(readFileSync(path, "utf8")));
+}
+const TOOL_NAME_HEADERS = new Set(["tool"]);
+const REST_NAME_HEADERS = new Set(["route", "endpoint", "surface"]);
+function splitTableRow(line) {
+    return line
+        .replace(/^\s*\|/, "")
+        .replace(/\|\s*$/, "")
+        .split("|")
+        .map((cell) => cell.trim());
+}
+function isSeparatorRow(cells) {
+    return cells.every((cell) => /^:?-{3,}:?$/.test(cell));
+}
+/**
+ * Expand one name cell into surface names. Backticked spans are the names;
+ * a span with no `.`, `/`, or space is shorthand for a sibling of the first
+ * span (Slack-style `` `reactions.add` / `remove` / `get` ``) and inherits
+ * its dotted prefix. Cells with no backticks name the surface verbatim
+ * (e.g. "Any unsupported path").
+ */
+export function expandSurfaceCell(cell) {
+    const spans = [...cell.matchAll(/`([^`]+)`/g)].map((match) => match[1].trim());
+    if (spans.length === 0) {
+        const text = cell.trim();
+        return text.length > 0 ? [text] : [];
+    }
+    const [first, ...rest] = spans;
+    const lastDot = first.lastIndexOf(".");
+    const prefix = lastDot >= 0 ? first.slice(0, lastDot + 1) : "";
+    return [
+        first,
+        ...rest.map((span) => /[./ ]/.test(span) || prefix === "" ? span : `${prefix}${span}`),
+    ];
+}
+/**
+ * Parse every markdown table whose header names surfaces of `kind` + Tier.
+ * The Heat column (ENDPOINT-TIERS.md) is optional: parsed when the header
+ * names it, omitted otherwise, so pre-heat tables stay legal.
+ */
+export function parseFidelityDocRows(markdown, kind) {
+    const nameHeaders = kind === "tool" ? TOOL_NAME_HEADERS : REST_NAME_HEADERS;
+    const rows = [];
+    const lines = markdown.split("\n");
+    let nameIdx = -1;
+    let tierIdx = -1;
+    let heatIdx = -1;
+    let inTable = false;
+    for (const line of lines) {
+        if (!line.trimStart().startsWith("|")) {
+            inTable = false;
+            nameIdx = -1;
+            tierIdx = -1;
+            heatIdx = -1;
+            continue;
+        }
+        const cells = splitTableRow(line);
+        if (!inTable) {
+            const headers = cells.map((cell) => cell.toLowerCase());
+            nameIdx = headers.findIndex((header) => nameHeaders.has(header));
+            tierIdx = headers.findIndex((header) => header === "tier");
+            heatIdx = headers.findIndex((header) => header === "heat");
+            inTable = true;
+            continue;
+        }
+        if (isSeparatorRow(cells) || nameIdx < 0 || tierIdx < 0)
+            continue;
+        const fidelity = cells[tierIdx] ?? "";
+        const heat = heatIdx >= 0 ? { heat: cells[heatIdx] ?? "" } : {};
+        for (const name of expandSurfaceCell(cells[nameIdx] ?? "")) {
+            rows.push({ name, fidelity, ...heat });
+        }
+    }
+    return rows;
+}
+// ─── Lint: inventory ⇔ docs, both directions ─────────────────────────────────
+/**
+ * 1:1-lint the inventory against the FIDELITY doc tables. Returns human-
+ * readable problems (empty = clean). Directions checked per kind:
+ * every doc row must be in the inventory with the same fidelity tier, and
+ * every inventory entry must be documented unless a `doc_drift` entry
+ * (with its owning ticket) declares the gap. A drift declaration whose
+ * name IS documented is stale and reported, so drift entries self-expire.
+ */
+export function lintFidelityInventory(inventory, docs) {
+    const problems = [];
+    for (const kind of ["tool", "rest"]) {
+        const sources = docs.filter((doc) => doc.kind === kind);
+        if (sources.length === 0)
+            continue;
+        const labels = sources.map((doc) => doc.label).join(", ");
+        const entries = kind === "tool" ? inventory.tools : inventory.rest;
+        const drift = new Map(inventory.doc_drift.filter((d) => d.kind === kind).map((d) => [d.name, d]));
+        const inventoryByName = new Map();
+        for (const entry of entries) {
+            if (inventoryByName.has(entry.name)) {
+                problems.push(`inventory ${kind} '${entry.name}' is listed twice`);
+            }
+            inventoryByName.set(entry.name, entry);
+        }
+        const documented = new Map();
+        for (const source of sources) {
+            for (const row of parseFidelityDocRows(source.markdown, kind)) {
+                const existing = documented.get(row.name);
+                if (existing && existing.fidelity !== row.fidelity) {
+                    problems.push(`${labels}: ${kind} '${row.name}' is documented twice with conflicting tiers ('${existing.fidelity}' vs '${row.fidelity}')`);
+                    continue;
+                }
+                if (existing &&
+                    existing.heat !== undefined &&
+                    row.heat !== undefined &&
+                    existing.heat !== row.heat) {
+                    problems.push(`${labels}: ${kind} '${row.name}' is documented twice with conflicting heat ('${existing.heat}' vs '${row.heat}')`);
+                    continue;
+                }
+                documented.set(row.name, row);
+            }
+        }
+        for (const [name, row] of documented) {
+            const entry = inventoryByName.get(name);
+            if (!entry) {
+                problems.push(`${labels}: ${kind} '${name}' documented but missing from fidelity.inventory.json`);
+                continue;
+            }
+            if (entry.fidelity !== row.fidelity) {
+                problems.push(`${kind} '${name}': inventory says fidelity '${entry.fidelity}' but ${labels} says '${row.fidelity}'`);
+            }
+            if (row.heat !== undefined && entry.heat !== row.heat) {
+                problems.push(`${kind} '${name}': inventory says heat '${entry.heat}' but ${labels} says '${row.heat}'`);
+            }
+        }
+        for (const entry of entries) {
+            if (documented.has(entry.name))
+                continue;
+            const declared = drift.get(entry.name);
+            if (!declared) {
+                problems.push(`${kind} '${entry.name}' is in fidelity.inventory.json but undocumented in ${labels}; add the row or declare doc_drift`);
+            }
+        }
+        for (const declared of drift.values()) {
+            if (!inventoryByName.has(declared.name)) {
+                problems.push(`doc_drift ${kind} '${declared.name}' (${declared.ticket}) matches no inventory entry`);
+            }
+            if (documented.has(declared.name)) {
+                problems.push(`doc_drift ${kind} '${declared.name}' (${declared.ticket}) is stale — ${labels} now documents it; remove the declaration`);
+            }
+        }
+    }
+    return problems;
+}
+/** Set-compare tool names: inventory vs the live `listTools()` surface. */
+export function compareToolNames(inventoryNames, liveNames) {
+    const inventory = new Set(inventoryNames);
+    const live = new Set(liveNames);
+    return {
+        missing: [...live].filter((name) => !inventory.has(name)).sort(),
+        extra: [...inventory].filter((name) => !live.has(name)).sort(),
+    };
+}
+//# sourceMappingURL=fidelity-inventory.js.map

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

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

package/node_modules/@pome-sh/twin-gmail/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/twin-gmail/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/twin-gmail/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/twin-gmail/node_modules/@pome-sh/sdk/dist/index.d.ts

@@ -0,0 +1,372 @@
+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>;
+    /**
+     * Whether this tool's handler actually mutates local twin state when it
+     * succeeds. Independent of upstream MCP `annotations` (e.g. Google's
+     * `readOnlyHint`): annotations are served verbatim for wire parity;
+     * `mutation` remains Pome's recorder truth for `state_mutation`.
+     */
+    mutation: boolean;
+    fidelity?: ToolFidelityMetadata;
+    /**
+     * Optional MCP tool title. Emitted on tool-list surfaces only when set —
+     * existing twins omit it and stay wire-identical.
+     */
+    title?: string;
+    /**
+     * MCP tool-list annotations (e.g. `{ readOnlyHint: true }`), emitted
+     * verbatim on both tool-list surfaces when present. Do not derive
+     * `mutation` from these hints — they are upstream metadata only.
+     */
+    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>;
+    /**
+     * Optional MCP output JSON Schema. When set, `tools/list` advertises it
+     * and successful `tools/call` results include `structuredContent` equal
+     * to the handler return value. Omitted tools stay byte-identical.
+     */
+    outputSchema?: Record<string, unknown>;
+    /**
+     * Optional text-content projection for JSON-RPC `tools/call`. The
+     * structured value remains the validated handler return value.
+     */
+    contentText?: (output: TOutput) => string;
+    /** Emit the explicit MCP `isError: false` success marker when captured upstream. */
+    includeIsError?: boolean;
+}
+/** The JSON-Schema a tool advertises: the declared override, else zod-derived. */
+export declare function toolInputSchema(tool: Pick<ToolSpec, "schema" | "inputSchema">): Record<string, unknown>;
+/**
+ * Optional MCP tool-list fields that must stay absent when unset so existing
+ * GitHub/Slack/Stripe listings remain byte-identical.
+ */
+export declare function toolListExtras(tool: Pick<ToolSpec, "title" | "outputSchema" | "annotations">): 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;
+    /**
+     * Optional pre-redaction projection applied to every recorded event
+     * before the central secret scrubber. Use to replace large/binary
+     * payloads (e.g. MIME/attachment bytes) with bounded digests. When
+     * unset, recording behavior is unchanged.
+     */
+    recordingProjection?: (event: RecorderEvent) => RecorderEvent;
+}
+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"];