@synoikia/core 0.1.0

package/dist/gate/attestation.d.ts

@@ -0,0 +1,23 @@
+import type { DbLike } from '../db/index.js';
+/**
+ * Best-practice attestation (HA §3.6, design §5.1/§5.2 step 1). `search` hands out a key bound to
+ * (instance, operation, guide version, MCP session); `execute` must present it from the same session.
+ * Revising the guide invalidates every outstanding key at once, because the version is part of the
+ * MAC, and a key read in one session (or leaked into a prompt) is useless in any other.
+ */
+export declare function issueAttestationKey(macKey: Buffer, instanceId: string, opKey: string, guideVersion: string, mcpSessionId?: string): string;
+export declare function currentGuide(db: DbLike, instanceId: string, operationId: string): {
+    id: string;
+    instanceId: string;
+    operationId: string;
+    version: string;
+    content: string;
+    fetchedAt: Date;
+} | undefined;
+export declare function verifyAttestationKey(db: DbLike, macKey: Buffer, input: {
+    instanceId: string;
+    operationId: string;
+    opKey: string;
+    mcpSessionId?: string;
+    presented: unknown;
+}): boolean;

package/dist/gate/attestation.js

@@ -0,0 +1,33 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { and, desc, eq } from 'drizzle-orm';
+import { guides } from '../db/schema.js';
+/**
+ * Best-practice attestation (HA §3.6, design §5.1/§5.2 step 1). `search` hands out a key bound to
+ * (instance, operation, guide version, MCP session); `execute` must present it from the same session.
+ * Revising the guide invalidates every outstanding key at once, because the version is part of the
+ * MAC, and a key read in one session (or leaked into a prompt) is useless in any other.
+ */
+export function issueAttestationKey(macKey, instanceId, opKey, guideVersion, mcpSessionId = '') {
+    return createHmac('sha256', macKey)
+        .update(`${instanceId}\n${opKey}\n${guideVersion}\n${mcpSessionId}`)
+        .digest('base64url');
+}
+export function currentGuide(db, instanceId, operationId) {
+    return db
+        .select()
+        .from(guides)
+        .where(and(eq(guides.instanceId, instanceId), eq(guides.operationId, operationId)))
+        .orderBy(desc(guides.fetchedAt))
+        .get();
+}
+export function verifyAttestationKey(db, macKey, input) {
+    if (typeof input.presented !== 'string' || input.presented === '')
+        return false;
+    const guide = currentGuide(db, input.instanceId, input.operationId);
+    if (!guide)
+        return false;
+    const expected = Buffer.from(issueAttestationKey(macKey, input.instanceId, input.opKey, guide.version, input.mcpSessionId));
+    const presented = Buffer.from(input.presented);
+    return presented.length === expected.length && timingSafeEqual(presented, expected);
+}
+//# sourceMappingURL=attestation.js.map

package/dist/gate/attestation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attestation.js","sourceRoot":"","sources":["../../src/gate/attestation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC;;;;;GAKG;AAEH,MAAM,UAAU,mBAAmB,CACjC,MAAc,EACd,UAAkB,EAClB,KAAa,EACb,YAAoB,EACpB,YAAY,GAAG,EAAE;IAEjB,OAAO,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC;SAChC,MAAM,CAAC,GAAG,UAAU,KAAK,KAAK,KAAK,YAAY,KAAK,YAAY,EAAE,CAAC;SACnE,MAAM,CAAC,WAAW,CAAC,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,EAAU,EAAE,UAAkB,EAAE,WAAmB;IAC9E,OAAO,EAAE;SACN,MAAM,EAAE;SACR,IAAI,CAAC,MAAM,CAAC;SACZ,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;SAClF,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;SAC/B,GAAG,EAAE,CAAC;AACX,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,EAAU,EACV,MAAc,EACd,KAA4G;IAE5G,IAAI,OAAO,KAAK,CAAC,SAAS,KAAK,QAAQ,IAAI,KAAK,CAAC,SAAS,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IAChF,MAAM,KAAK,GAAG,YAAY,CAAC,EAAE,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IACpE,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAC1B,mBAAmB,CAAC,MAAM,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC,CAC9F,CAAC;IACF,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAC/C,OAAO,SAAS,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,IAAI,eAAe,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AACtF,CAAC"}

package/dist/gate/canonical.d.ts

@@ -0,0 +1,3 @@
+/** JSON with object keys sorted recursively, so equal values always serialize identically. */
+export declare function canonicalJson(value: unknown): string;
+export declare function sha256Hex(input: string): string;

package/dist/gate/canonical.js

@@ -0,0 +1,11 @@
+import { createHash } from 'node:crypto';
+/** JSON with object keys sorted recursively, so equal values always serialize identically. */
+export function canonicalJson(value) {
+    return (JSON.stringify(value, (_key, v) => v && typeof v === 'object' && !Array.isArray(v)
+        ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+        : v) ?? 'null');
+}
+export function sha256Hex(input) {
+    return createHash('sha256').update(input).digest('hex');
+}
+//# sourceMappingURL=canonical.js.map

package/dist/gate/canonical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.js","sourceRoot":"","sources":["../../src/gate/canonical.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,8FAA8F;AAC9F,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,CACL,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,CAAU,EAAE,EAAE,CACzC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAC7C,CAAC,CAAC,MAAM,CAAC,WAAW,CAChB,MAAM,CAAC,OAAO,CAAC,CAA4B,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAC9F;QACH,CAAC,CAAC,CAAC,CACN,IAAI,MAAM,CACZ,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC"}

package/dist/gate/match.d.ts

@@ -0,0 +1,67 @@
+import type { ResolvedTarget } from '@synoikia/plugin-sdk';
+import { z } from 'zod';
+/**
+ * Pre-approval `match` evaluator (design §5.2). A rule's match is a list of conditions that must all
+ * hold. It fails closed: a missing field, a type mismatch or zero resolved targets means "no match",
+ * which only ever sends the call to a human.
+ *
+ * Matching is **strict**: every parameter of the call must be covered by a condition. A parameter the
+ * rule doesn't mention must be absent, unless the rule accepts it with `{ field, op: 'any' }` (`field: ''`
+ * accepts all parameters). Otherwise a rule for one field would also approve whatever else the model
+ * chose to send (a quota, an ACL, encryption options).
+ */
+export declare const PARAM_OPS: readonly ["eq", "in", "prefix", "range", "bool", "any"];
+export declare const ParamConditionSchema: z.ZodObject<{
+    field: z.ZodString;
+    op: z.ZodEnum<{
+        any: "any";
+        in: "in";
+        eq: "eq";
+        prefix: "prefix";
+        range: "range";
+        bool: "bool";
+    }>;
+    value: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export declare const TargetConditionSchema: z.ZodObject<{
+    field: z.ZodLiteral<"$targets">;
+    areas: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    entities: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    domains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const MatchSchema: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+    field: z.ZodLiteral<"$targets">;
+    areas: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    entities: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    domains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    field: z.ZodString;
+    op: z.ZodEnum<{
+        any: "any";
+        in: "in";
+        eq: "eq";
+        prefix: "prefix";
+        range: "range";
+        bool: "bool";
+    }>;
+    value: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>]>>;
+export type MatchCondition = z.infer<typeof MatchSchema>[number];
+/** RFC 6901 JSON pointer lookup; returns MISSING instead of undefined so `null` values still count. */
+export declare function getPointer(doc: unknown, pointer: string): unknown;
+/**
+ * Whether every parameter is covered by some condition: a condition on a path covers everything under
+ * it; an object or array only partly covered has each of its keys (or indexes: `/0/name`) checked in
+ * turn. Nothing (or `{}` / `[]`) is covered. Arrays matter for positional APIs such as TrueNAS, whose
+ * params are `[{ name, … }]`.
+ */
+export declare function coversAllParams(match: readonly MatchCondition[], params: unknown): boolean;
+/** The conditions alone, without the strict every-parameter check (used to spot rules strictness broke). */
+export declare function conditionsHold(match: readonly MatchCondition[], call: {
+    params: unknown;
+    targets: readonly ResolvedTarget[];
+}): boolean;
+export declare function matches(match: readonly MatchCondition[], call: {
+    params: unknown;
+    targets: readonly ResolvedTarget[];
+}): boolean;

package/dist/gate/match.js

@@ -0,0 +1,133 @@
+import { MATCH_OPS } from '@synoikia/plugin-sdk';
+import { z } from 'zod';
+import { canonicalJson } from './canonical.js';
+/**
+ * Pre-approval `match` evaluator (design §5.2). A rule's match is a list of conditions that must all
+ * hold. It fails closed: a missing field, a type mismatch or zero resolved targets means "no match",
+ * which only ever sends the call to a human.
+ *
+ * Matching is **strict**: every parameter of the call must be covered by a condition. A parameter the
+ * rule doesn't mention must be absent, unless the rule accepts it with `{ field, op: 'any' }` (`field: ''`
+ * accepts all parameters). Otherwise a rule for one field would also approve whatever else the model
+ * chose to send (a quota, an ACL, encryption options).
+ */
+export const PARAM_OPS = [...MATCH_OPS, 'any'];
+export const ParamConditionSchema = z
+    .object({
+    field: z.string().regex(/^(\/.*)?$/, 'must be a JSON pointer'),
+    op: z.enum(PARAM_OPS),
+    value: z.unknown().optional(),
+})
+    .refine((c) => c.op === 'any' || c.field !== '', 'only "any" can apply to all parameters');
+export const TargetConditionSchema = z
+    .object({
+    field: z.literal('$targets'),
+    areas: z.array(z.string()).optional(),
+    entities: z.array(z.string()).optional(),
+    domains: z.array(z.string()).optional(),
+})
+    .refine((c) => c.areas?.length || c.entities?.length || c.domains?.length, 'select at least one area, entity or domain');
+export const MatchSchema = z.array(z.union([TargetConditionSchema, ParamConditionSchema]));
+const MISSING = Symbol('missing');
+/** RFC 6901 JSON pointer lookup; returns MISSING instead of undefined so `null` values still count. */
+export function getPointer(doc, pointer) {
+    if (pointer === '')
+        return doc;
+    let cur = doc;
+    for (const raw of pointer.slice(1).split('/')) {
+        const key = raw.replace(/~1/g, '/').replace(/~0/g, '~');
+        if (cur === null || typeof cur !== 'object' || !Object.prototype.hasOwnProperty.call(cur, key))
+            return MISSING;
+        cur = cur[key];
+    }
+    return cur;
+}
+function paramMatches(actual, op, expected) {
+    if (op === 'any')
+        return true; // present or not, any value
+    if (actual === MISSING)
+        return false;
+    switch (op) {
+        case 'eq':
+            return canonicalJson(actual) === canonicalJson(expected);
+        case 'in': {
+            if (!Array.isArray(expected))
+                return false;
+            const allowed = new Set(expected.map((v) => canonicalJson(v)));
+            const values = Array.isArray(actual) ? actual : [actual];
+            return values.length > 0 && values.every((v) => allowed.has(canonicalJson(v)));
+        }
+        case 'prefix':
+            // Path-segment boundary: "tank/media" matches "tank/media" and "tank/media/tv", not "tank/media-private".
+            return (typeof actual === 'string' &&
+                typeof expected === 'string' &&
+                expected !== '' &&
+                (actual === expected ||
+                    (actual.startsWith(expected) && (expected.endsWith('/') || actual[expected.length] === '/'))));
+        case 'range': {
+            const { min, max } = (expected ?? {});
+            if (typeof actual !== 'number' || !Number.isFinite(actual))
+                return false;
+            if (min === undefined && max === undefined)
+                return false;
+            if (min !== undefined && (typeof min !== 'number' || actual < min))
+                return false;
+            if (max !== undefined && (typeof max !== 'number' || actual > max))
+                return false;
+            return true;
+        }
+        case 'bool':
+            return typeof actual === 'boolean' && actual === expected;
+        default:
+            return false;
+    }
+}
+function targetMatches(target, c) {
+    if (c.areas?.length && !c.areas.includes(target.scopes?.area ?? ''))
+        return false;
+    if (c.entities?.length && !c.entities.includes(target.id))
+        return false;
+    if (c.domains?.length && !c.domains.includes(target.scopes?.domain ?? ''))
+        return false;
+    return true;
+}
+const escapePointer = (key) => key.replace(/~/g, '~0').replace(/\//g, '~1');
+/**
+ * Whether every parameter is covered by some condition: a condition on a path covers everything under
+ * it; an object or array only partly covered has each of its keys (or indexes: `/0/name`) checked in
+ * turn. Nothing (or `{}` / `[]`) is covered. Arrays matter for positional APIs such as TrueNAS, whose
+ * params are `[{ name, … }]`.
+ */
+export function coversAllParams(match, params) {
+    const pointers = match.filter((c) => c.field !== '$targets').map((c) => c.field);
+    const covered = (value, path) => {
+        if (pointers.includes(path))
+            return true;
+        if (value === undefined || value === null)
+            return path === '';
+        if (typeof value !== 'object')
+            return false;
+        const entries = Array.isArray(value) ? value.map((v, i) => [String(i), v]) : Object.entries(value);
+        if (entries.length === 0)
+            return true;
+        if (!pointers.some((p) => p.startsWith(`${path}/`)))
+            return false;
+        return entries.every(([k, v]) => covered(v, `${path}/${escapePointer(k)}`));
+    };
+    return covered(params, '');
+}
+/** The conditions alone, without the strict every-parameter check (used to spot rules strictness broke). */
+export function conditionsHold(match, call) {
+    return match.every((c) => {
+        if (c.field === '$targets') {
+            const tc = c;
+            return call.targets.length > 0 && call.targets.every((t) => targetMatches(t, tc));
+        }
+        const pc = c;
+        return paramMatches(getPointer(call.params, pc.field), pc.op, pc.value);
+    });
+}
+export function matches(match, call) {
+    return conditionsHold(match, call) && coversAllParams(match, call.params);
+}
+//# sourceMappingURL=match.js.map

package/dist/gate/match.js.map

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

package/dist/gate/pipeline.d.ts

@@ -0,0 +1,61 @@
+import type { Manifest } from '@synoikia/plugin-sdk';
+import type { ApprovalService, ClientPrompts } from '../approvals/service.js';
+import type { Db } from '../db/index.js';
+import type { AccessPrincipal } from './access.js';
+import type { InstanceSettings } from '../instances/settings.js';
+import type { PluginProcess } from '../plugins/process.js';
+import type { Binding } from '../sandbox/index.js';
+import type { SlidingWindowLimiter } from './rate-limit.js';
+import type { Redactor } from './redact.js';
+/**
+ * The permission gate (design §5.2): the only path from sandboxed code to a plugin's `invoke`.
+ *
+ *   resolveOperation → attestation → access level → resolveTargets → prepareWrite
+ *   → [level ask: pre-approval rule (never for locked) → human approval] → invoke → redact → audit
+ *
+ * Reads run straight away; acknowledged writes at level `write` are auto-approved.
+ *
+ * Every branch, including every rejection, writes one `call` audit event. Calls within one
+ * `execute` run strictly one at a time, so a pending approval blocks the whole script (TN §3.1).
+ */
+export interface GateDeps {
+    db: Db;
+    approvals: ApprovalService;
+    limiter: SlidingWindowLimiter;
+    attestationKey: Buffer;
+    now?: () => Date;
+}
+export interface InstanceRuntime {
+    instanceId: string;
+    slug: string;
+    manifest: Manifest;
+    settings: InstanceSettings;
+    redact: Redactor;
+    /** The live plugin process; throws PluginUnavailableError while it is down. */
+    plugin: () => PluginProcess;
+}
+export interface CallerContext {
+    /**
+     * `id` is the readable label recorded in the audit log (`token:Claude`); `key` is the stable
+     * principal (token id, grant id, external identity) that per-principal limits are keyed on, since
+     * two tokens may share a name.
+     */
+    client: {
+        kind: 'mcp_client';
+        id?: string;
+        key?: string;
+    };
+    mcpSessionId?: string;
+    /** The authenticated principal's access ceiling (consent page / bearer token). */
+    principal: AccessPrincipal;
+    /** Present only for a live session whose client advertised elicitation. */
+    prompts?: ClientPrompts;
+}
+/** What per-principal limits are keyed on: the stable principal, never the display name. */
+export declare const principalKey: (caller: CallerContext) => string;
+/**
+ * The gate bindings for one `execute` run. `signal` ends the run: once it is aborted (the sandbox
+ * settled, the MCP request was cancelled, or the session closed), calls the script left behind are
+ * refused and an approval still open is cancelled, so nothing runs after the tool call has returned.
+ */
+export declare function createGateBindings(deps: GateDeps, rt: InstanceRuntime, caller: CallerContext, signal?: AbortSignal): Record<string, Record<string, Binding>>;

package/dist/gate/pipeline.js

@@ -0,0 +1,284 @@
+import { randomUUID } from 'node:crypto';
+import { and, eq } from 'drizzle-orm';
+import { writeAudit } from '../audit.js';
+import { resolveAccess } from '../catalog/groups.js';
+import { operations } from '../db/schema.js';
+import { PluginProtocolError, PluginRpcError, PluginTimeoutError, PluginUnavailableError } from '../plugins/process.js';
+import { BindingError } from '../sandbox/index.js';
+import { verifyAttestationKey } from './attestation.js';
+import { canonicalJson, sha256Hex } from './canonical.js';
+import { evaluatePreApproval } from './preapproval.js';
+/** What per-principal limits are keyed on: the stable principal, never the display name. */
+export const principalKey = (caller) => caller.client.key ?? caller.client.id ?? 'anonymous';
+const MAX_ERROR_MESSAGE = 500;
+const PASSTHROUGH_PLUGIN_CODES = new Set([
+    'UNKNOWN_OPERATION',
+    'INVALID_PARAMS',
+    'TARGET_RESOLUTION_FAILED',
+    'CONFIG_CONFLICT',
+    'UPSTREAM_DENIED',
+    'UPSTREAM_ERROR',
+]);
+function toBindingError(err) {
+    if (err instanceof BindingError)
+        return err;
+    if (err instanceof PluginRpcError) {
+        const code = PASSTHROUGH_PLUGIN_CODES.has(err.code) ? err.code : 'PLUGIN_ERROR';
+        return new BindingError(code, err.message.slice(0, MAX_ERROR_MESSAGE));
+    }
+    if (err instanceof PluginUnavailableError)
+        return new BindingError('PLUGIN_UNAVAILABLE', 'The plugin is not running; try again shortly');
+    if (err instanceof PluginTimeoutError)
+        return new BindingError('UPSTREAM_TIMEOUT', err.message);
+    if (err instanceof PluginProtocolError)
+        return new BindingError('PLUGIN_ERROR', 'The plugin returned an invalid response');
+    return new BindingError('INTERNAL', 'Internal error');
+}
+const DISABLED_MESSAGES = {
+    group_missing: 'is not available on this endpoint',
+    level_none: 'is disabled on this endpoint (access level None)',
+    read_only: 'is a write, and its access level on this endpoint is Read',
+    token_read_only: 'is a write, and this connection was granted read-only access',
+    locked_not_opted_in: 'is a protected operation that the administrator has not enabled',
+    unknown_operation: 'is not in the current catalog',
+};
+/** Order-independent identity of a resolved target set. */
+const targetKey = (targets) => JSON.stringify(targets.map((t) => `${t.kind}:${t.id}`).sort());
+const DENIAL_MESSAGES = {
+    no_approval_path: 'needs approval, and this MCP client cannot show approval prompts',
+    client_cannot_approve: 'needs approval on a web page, and this MCP client only supports form prompts; use a client that supports URL elicitation',
+    declined: 'was declined in the client',
+    prompt_failed: 'needs approval, but the client could not show the approval prompt',
+    confirmation_mismatch: 'was denied (confirmation mismatch)',
+    endpoint_stopped: 'was cancelled: the endpoint was stopped or reconfigured while it waited for approval',
+};
+/**
+ * The gate bindings for one `execute` run. `signal` ends the run: once it is aborted (the sandbox
+ * settled, the MCP request was cancelled, or the session closed), calls the script left behind are
+ * refused and an approval still open is cancelled, so nothing runs after the tool call has returned.
+ */
+export function createGateBindings(deps, rt, caller, signal = new AbortController().signal) {
+    const now = deps.now ?? (() => new Date());
+    const executionId = randomUUID();
+    let queue = Promise.resolve();
+    const openApprovals = new Set();
+    signal.addEventListener('abort', () => {
+        for (const id of openApprovals)
+            deps.approvals.cancel(id, 'execution_ended');
+    });
+    const serialized = (fn) => (args, budget) => {
+        const run = queue.then(() => gatedCall(fn, args, budget));
+        queue = run.catch(() => undefined);
+        return run;
+    };
+    async function gatedCall(fn, args, budget) {
+        const started = Date.now();
+        const audit = {
+            kind: 'call',
+            instanceId: rt.instanceId,
+            actorKind: 'mcp_client',
+            actorId: caller.client.id,
+            detail: { executionId, fn },
+        };
+        let audited = false;
+        const finish = (decision, extra = {}) => {
+            audited = true;
+            writeAudit(deps.db, {
+                ...audit,
+                decision,
+                resultStatus: extra.resultStatus ?? null,
+                durationMs: Date.now() - started,
+                detail: { ...audit.detail, ...extra.detail },
+            }, now());
+        };
+        const reject = (decision, err) => {
+            finish(decision, { resultStatus: 'rejected', detail: { error: err.code } });
+            throw err;
+        };
+        const ensureRunning = () => {
+            if (signal.aborted)
+                reject('rejected:execution_ended', new BindingError('EXECUTION_ENDED', 'The execute call this belongs to has already ended'));
+        };
+        try {
+            ensureRunning();
+            // 0. Map the raw binding call onto a catalog key (Seerr path templates, HA garage-door split…).
+            const resolved = await rt.plugin().call('resolveOperation', { fn, args });
+            audit.operationKey = resolved.key;
+            const op = deps.db
+                .select()
+                .from(operations)
+                .where(and(eq(operations.instanceId, rt.instanceId), eq(operations.key, resolved.key)))
+                .get();
+            audit.params = rt.redact(resolved.params);
+            // 1. Attestation, before anything else about the op is revealed (HA §3.6).
+            if (op && !op.stale && op.attestationRequired) {
+                const presented = resolved.params?.best_practice_key;
+                if (!verifyAttestationKey(deps.db, deps.attestationKey, {
+                    instanceId: rt.instanceId,
+                    operationId: op.id,
+                    opKey: op.key,
+                    mcpSessionId: caller.mcpSessionId,
+                    presented,
+                })) {
+                    reject('rejected:attestation_required', new BindingError('ATTESTATION_REQUIRED', `Call search() for the ${op.key} guide first and pass its best_practice_key`));
+                }
+            }
+            // 2. Access level (operation's own, else its group's) under the principal's ceiling. Unknown or
+            //    stale ops fail here too.
+            const access = resolveAccess(deps.db, rt.instanceId, resolved.key, caller.principal);
+            if (!access.reachable || !op) {
+                const reason = access.reachable ? 'unknown_operation' : access.reason;
+                reject(`rejected:${reason}`, Object.assign(new BindingError('OPERATION_DISABLED', `${resolved.key} ${DISABLED_MESSAGES[reason] ?? 'is not available'}`), { reason }));
+            }
+            const operation = op;
+            const mode = access.reachable ? access.mode : 'run';
+            const isWrite = mode !== 'run';
+            audit.classification = operation.locked ? 'locked' : operation.classification;
+            // 3. Concrete targets, so rules and approvers see exactly what will be touched. Fails closed.
+            let targets = [];
+            if (rt.manifest.capabilities.targets) {
+                targets = await rt.plugin().call('resolveTargets', { key: operation.key, params: resolved.params });
+                audit.resolvedTargets = targets;
+            }
+            // 4. Config transforms: compute the real diff against the live object (HA §2.8).
+            let params = resolved.params;
+            let diff;
+            let expectedHash;
+            if (isWrite && rt.manifest.capabilities.configTransform && operation.kind === 'config') {
+                const prepared = await rt.plugin().call('prepareWrite', { key: operation.key, params });
+                params = prepared.params;
+                diff = prepared.diff;
+                expectedHash = prepared.expectedHash;
+            }
+            // 5. Reads run straight away.
+            let decision = 'auto-executed';
+            let approval;
+            // Each principal has its own write budget, charged only for writes that actually run (step 9):
+            // a noisy, denied or timed-out client doesn't use up anyone else's.
+            const writeBucket = `write:${rt.instanceId}:${principalKey(caller)}`;
+            const overWriteBudget = () => reject('rejected:rate_limited', new BindingError('RATE_LIMITED', 'Too many write calls; slow down'));
+            if (isWrite) {
+                // Checked before asking anyone, so nobody approves a call that would be refused anyway.
+                if (!deps.limiter.allows(writeBucket, rt.settings.writesPerMinute, 60_000))
+                    overWriteBudget();
+                // 6. Level `write`: acknowledged writes are auto-approved. Level `ask`: pre-approval rules, which
+                //    never cover locked ops (TN §3.4) nor writes still waiting for acknowledgement.
+                let preapproved = false;
+                if (mode === 'auto') {
+                    preapproved = true;
+                    decision = 'auto-approved:level';
+                }
+                else if (!operation.locked && access.reachable && access.level === 'ask') {
+                    const outcome = evaluatePreApproval(deps.db, { instanceId: rt.instanceId, operationId: operation.id, params, targets }, now());
+                    if (outcome.kind === 'auto_approved') {
+                        preapproved = true;
+                        decision = `auto-approved:rule:${outcome.ruleId}`;
+                    }
+                    else if (outcome.kind === 'rate_limited') {
+                        audit.detail.rateLimitedRules = outcome.ruleIds;
+                    }
+                }
+                // 7. Human approval, scoped to exactly these params and targets.
+                if (!preapproved) {
+                    // The plugin only sees redacted params here: summaries and confirmation literals end up in
+                    // prompts, the DB and notifications, and never need a secret.
+                    const summary = await rt
+                        .plugin()
+                        .call('summarize', { key: operation.key, params: rt.redact(params), targets });
+                    if (operation.typedConfirmation && !summary.confirmLiteral) {
+                        reject('rejected:missing_confirmation_literal', new BindingError('PLUGIN_ERROR', `The plugin did not provide a confirmation value for ${operation.key}`));
+                    }
+                    ensureRunning();
+                    const paramsHash = sha256Hex(canonicalJson({ key: operation.key, params, targets, expectedHash: expectedHash ?? null }));
+                    const request = deps.approvals.request({
+                        instanceId: rt.instanceId,
+                        operationId: operation.id,
+                        operationKey: operation.key,
+                        classification: audit.classification,
+                        paramsDisplay: rt.redact(params),
+                        paramsHash,
+                        resolvedTargets: targets,
+                        summary: summary.text,
+                        confirmLiteral: operation.typedConfirmation ? summary.confirmLiteral : undefined,
+                        diff,
+                        expectedHash,
+                        client: caller.client,
+                        mcpSessionId: caller.mcpSessionId,
+                        timeoutMs: rt.settings.approvalTimeoutMs,
+                        prompts: caller.prompts,
+                        formApprovals: rt.settings.formElicitationApprovals === 'writes' && !operation.locked && !operation.typedConfirmation,
+                    });
+                    audit.detail.approvalId = request.id;
+                    openApprovals.add(request.id);
+                    budget.pause();
+                    try {
+                        approval = await request.decision;
+                    }
+                    finally {
+                        openApprovals.delete(request.id);
+                        budget.resume();
+                    }
+                    audit.decidedBy = approval.decidedBy;
+                    audit.decidedVia = approval.via;
+                    if (approval.outcome === 'cancelled' && signal.aborted)
+                        ensureRunning();
+                    if (approval.outcome !== 'approved') {
+                        const label = approval.outcome === 'timed_out' ? 'timed-out' : 'denied';
+                        reject(label, new BindingError('PERMISSION_DENIED', approval.outcome === 'timed_out'
+                            ? `Approval for ${operation.key} timed out and was denied`
+                            : `${operation.key} ${(approval.reason && DENIAL_MESSAGES[approval.reason]) ?? `was denied${approval.reason ? ` (${approval.reason})` : ''}`}`));
+                    }
+                    // The admin may have lowered the level while the approval was open: the call must still be allowed.
+                    const after = resolveAccess(deps.db, rt.instanceId, operation.key, caller.principal);
+                    if (!after.reachable || after.mode === 'run') {
+                        reject('rejected:access_changed', new BindingError('OPERATION_DISABLED', `${operation.key} was disabled while waiting for approval`));
+                    }
+                    decision = 'human-approved';
+                }
+            }
+            // 8. The approver saw these targets; after a wait they may have moved (an entity joined the area).
+            //    Resolve again and refuse unless the set is unchanged, then hand the plugin the approved set.
+            ensureRunning();
+            if (decision === 'human-approved' && rt.manifest.capabilities.targets) {
+                const now = await rt.plugin().call('resolveTargets', { key: operation.key, params });
+                if (targetKey(now) !== targetKey(targets)) {
+                    audit.detail.targetsNow = now;
+                    reject('rejected:targets_changed', new BindingError('TARGETS_CHANGED', `What ${operation.key} would act on changed while it waited for approval; call it again to get a fresh approval`));
+                }
+            }
+            // 9. The real upstream call, within what's left of the sandbox budget.
+            if (isWrite && !deps.limiter.take(writeBucket, rt.settings.writesPerMinute, 60_000))
+                overWriteBudget();
+            const remaining = Math.max(1, budget.remainingMs());
+            const result = await rt.plugin().call('invoke', {
+                key: operation.key,
+                params,
+                context: {
+                    callId: randomUUID(),
+                    expectedHash,
+                    deadlineMs: remaining,
+                    ...(rt.manifest.capabilities.targets ? { targets } : {}),
+                },
+            }, remaining);
+            // 10–11. Redact, audit, hand back.
+            finish(decision, { resultStatus: 'ok' });
+            return rt.redact(result);
+        }
+        catch (err) {
+            const raw = toBindingError(err);
+            // Plugin and upstream messages are free text: scrub the instance's secret values out of them.
+            const mapped = new BindingError(raw.code, rt.redact(raw.message));
+            Object.assign(mapped, { reason: raw.reason });
+            // Gate rejections were audited where they were raised; plugin/upstream failures are audited here.
+            if (!audited) {
+                const decision = audit.classification ? `error:${mapped.code}` : `rejected:${mapped.code.toLowerCase()}`;
+                finish(decision, { resultStatus: 'error', detail: { error: mapped.code } });
+            }
+            throw mapped;
+        }
+    }
+    return {
+        [rt.manifest.binding.namespace]: Object.fromEntries(rt.manifest.binding.functions.map((fn) => [fn, serialized(fn)])),
+    };
+}
+//# sourceMappingURL=pipeline.js.map