@affiant/core 0.1.0-alpha.0

package/dist/errors.js

@@ -0,0 +1,164 @@
+/**
+ * The error the gate throws, and the closed set of codes it throws with.
+ *
+ * **Rules served: CV-1** (hard-fail at wire-up; there is no disable switch),
+ * **AZ-4** (a requirement the implementation does not run is refused, never
+ * silently degraded).
+ *
+ * CV-1 in one sentence: *a misconfiguration the framework can detect fails at
+ * wire-up with a stated error, and no option turns the gate off for a tool it
+ * covers.* Every such failure is an {@link AffiantError} carrying one
+ * {@link ErrorCode} — a machine-readable reason a host can branch on and a
+ * conformance fixture can assert, rather than a message string that drifts.
+ *
+ * The codes are a closed union on purpose. A refusal that cannot be named here is
+ * a refusal no fixture can pin, and a host that cannot distinguish "you wired this
+ * wrong" from "the reviewer rejected it" will paper over the first.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Every reason the gate refuses, keyed by itself.
+ *
+ * The key and the value are the same string because the string *is* the API: it is
+ * what a fixture asserts and what a host branches on, so there is exactly one
+ * spelling to remember. Read a code as `ErrorCode["substance-refused"]`, or write
+ * the literal — both type-check.
+ *
+ * Three codes are marked **provisional**: they are named by the v0.1 design but the
+ * protocol rulebook does not yet carry an `ErrorCode` registry. When it does, those
+ * three are the ones that may be renamed to match it; the other seven describe
+ * behaviour the rulebook already fixes.
+ */
+export const ErrorCode = {
+    /**
+     * A requirement this implementation recognises but does not run — a `MultiParty`
+     * approval, a `ReferralRequired` referral — reached the pipeline. The entry is
+     * filed `pending` and marked blocked; every decision on it is refused. Never
+     * degraded to a weaker requirement (AZ-4).
+     *
+     * **Provisional** until the protocol's `ErrorCode` registry lands.
+     */
+    "requirement-not-implemented": "requirement-not-implemented",
+    /**
+     * A tool the gate must cover cannot be intercepted — it is write-capable with no
+     * `execute` to replace, it is executed by the model provider, or it is a hosted
+     * MCP tool. Raised at wire-up (CV-4, CV-1), or carried on a proposal from a tool
+     * the host explicitly declared uncovered.
+     *
+     * **Provisional** until the protocol's `ErrorCode` registry lands.
+     */
+    "coverage-refused": "coverage-refused",
+    /**
+     * A proposal reached the substance gate with nothing to swear to: no field
+     * carrying provenance other than `Empty`, or a non-empty value sitting under
+     * `Empty` provenance. Refused before anything is filed (GT-3).
+     */
+    "substance-refused": "substance-refused",
+    /**
+     * A decision was refused on identity grounds: the context carried no resolved
+     * principal, the entry belongs to another tenant, or the host's authorization
+     * port said no. Refused before the store is touched (AZ-2).
+     */
+    "decision-unauthorized": "decision-unauthorized",
+    /** A decision was made on an entry that is no longer `pending` (DK-1). */
+    "decision-not-pending": "decision-not-pending",
+    /**
+     * A decision was made on an entry that has passed its expiry. The entry reads
+     * `expired` whether or not the host's sweep has run; the decision's amendments
+     * are preserved on the row for a resubmission (DK-1).
+     */
+    "decision-expired": "decision-expired",
+    /**
+     * Two decisions raced for the same entry and this one lost the compare-and-set.
+     * A transition is applied once or not at all, never twice (DK-1).
+     */
+    "decision-lost-race": "decision-lost-race",
+    /**
+     * The gate was built wrong in a way it can detect: no store, no authorization
+     * port, a policy declaring a risk threshold with no scorer to compare against.
+     * Thrown from `createGate`, not on the first request (CV-1).
+     */
+    "wireup-invalid": "wireup-invalid",
+    /** No entry with that id is visible in the given scope (DK-1). */
+    "entry-not-found": "entry-not-found",
+    /**
+     * An execution outcome was reported against a row that already carries one. The
+     * first report stands and the row is untouched: a decision, once recorded, is
+     * never edited in place, and an approved-but-failed write must stay
+     * distinguishable from an approved-and-committed one (DK-4, DK-1).
+     *
+     * A host that retries a write reports **once**, when it knows the outcome (AZ-5:
+     * an outbox is a retry of an already-attested write, not a second authorization
+     * path, and not a second fact about what happened).
+     *
+     * **Provisional** until the protocol's `ErrorCode` registry lands.
+     */
+    "execution-already-recorded": "execution-already-recorded",
+};
+/**
+ * Every {@link ErrorCode} value, in registry order. Pinned as data so a runtime
+ * check and a fixture can use the same list the type does.
+ *
+ * **The order only ever grows at the end.** A code is added by appending it, never
+ * by inserting one among the codes that already shipped: the list is what a host's
+ * exhaustiveness check and a parity manifest read, and a reordering would look like
+ * a rename to both.
+ */
+export const ERROR_CODES = [
+    "requirement-not-implemented",
+    "coverage-refused",
+    "substance-refused",
+    "decision-unauthorized",
+    "decision-not-pending",
+    "decision-expired",
+    "decision-lost-race",
+    "wireup-invalid",
+    "entry-not-found",
+    "execution-already-recorded",
+];
+/** Whether `value` is one of the codes in {@link ErrorCode}. */
+export function isErrorCode(value) {
+    return typeof value === "string" && ERROR_CODES.includes(value);
+}
+/**
+ * The error every refusal in this package throws.
+ *
+ * The `code` is the contract; the `message` is for a human reading a log. A host
+ * that branches on the message is doing it wrong, and a fixture that asserts on
+ * the message is asserting on prose.
+ */
+export class AffiantError extends Error {
+    /** Why the gate refused. */
+    code;
+    /** Structured context for the refusal. `{}` when the throwing site supplied none. */
+    details;
+    /**
+     * @param code    Why the gate refused.
+     * @param message A human-readable explanation. Defaults to the code itself.
+     * @param details Structured context for the refusal.
+     */
+    constructor(code, message, details) {
+        super(message ?? code);
+        this.name = "AffiantError";
+        this.code = code;
+        this.details = details ?? {};
+    }
+}
+/**
+ * Whether `value` is an {@link AffiantError}.
+ *
+ * `instanceof` first, then a structural check: a host can end up with two copies of
+ * this package in one process (a bundler, two versions in a dependency tree), and a
+ * `catch` that spans that boundary still has to give a true answer. The structural
+ * arm is deliberately narrow — an `Error` named `AffiantError` carrying a `code`
+ * from {@link ERROR_CODES}.
+ */
+export function isAffiantError(value) {
+    if (value instanceof AffiantError)
+        return true;
+    return (value instanceof Error &&
+        value.name === "AffiantError" &&
+        isErrorCode(value.code));
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB;;;;;;;OAOG;IACH,6BAA6B,EAAE,6BAA6B;IAC5D;;;;;;;OAOG;IACH,kBAAkB,EAAE,kBAAkB;IACtC;;;;OAIG;IACH,mBAAmB,EAAE,mBAAmB;IACxC;;;;OAIG;IACH,uBAAuB,EAAE,uBAAuB;IAChD,0EAA0E;IAC1E,sBAAsB,EAAE,sBAAsB;IAC9C;;;;OAIG;IACH,kBAAkB,EAAE,kBAAkB;IACtC;;;OAGG;IACH,oBAAoB,EAAE,oBAAoB;IAC1C;;;;OAIG;IACH,gBAAgB,EAAE,gBAAgB;IAClC,kEAAkE;IAClE,iBAAiB,EAAE,iBAAiB;IACpC;;;;;;;;;;;OAWG;IACH,4BAA4B,EAAE,4BAA4B;CAClD,CAAC;AAKX;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,6BAA6B;IAC7B,kBAAkB;IAClB,mBAAmB;IACnB,uBAAuB;IACvB,sBAAsB;IACtB,kBAAkB;IAClB,oBAAoB;IACpB,gBAAgB;IAChB,iBAAiB;IACjB,4BAA4B;CACW,CAAC;AAE1C,gEAAgE;AAChE,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,WAAiC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACzF,CAAC;AAcD;;;;;;GAMG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,4BAA4B;IACnB,IAAI,CAAY;IACzB,qFAAqF;IAC5E,OAAO,CAAsB;IAEtC;;;;OAIG;IACH,YAAY,IAAe,EAAE,OAAgB,EAAE,OAA6B;QAC1E,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,IAAI,EAAE,CAAC;IAC/B,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,IAAI,KAAK,YAAY,YAAY;QAAE,OAAO,IAAI,CAAC;IAC/C,OAAO,CACL,KAAK,YAAY,KAAK;QACtB,KAAK,CAAC,IAAI,KAAK,cAAc;QAC7B,WAAW,CAAE,KAAqC,CAAC,IAAI,CAAC,CACzD,CAAC;AACJ,CAAC"}

package/dist/gate/coverage.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Coverage: which tools the gate can actually intercept, and what happens to the
+ * ones it cannot.
+ *
+ * **Rules served: CV-4** (a write-capable tool in an uncovered category is refused at
+ * wire-up, or — where wire-up cannot see it — marked `blocked` with code
+ * `coverage-refused` on the Docket; it is never silently allowed to write),
+ * **CV-1** (the refusal is at wire-up and there is no option that turns the gate off
+ * for a tool it covers), **AZ-4** (the blocked marker and its codes).
+ *
+ * ## The three categories
+ *
+ * A tool is *uncovered* when there is nothing for the gate to replace:
+ *
+ * - `"no-execute"` — the tool declares no `execute`. There is no function to stand in
+ *   front of; whatever writes, writes somewhere this package cannot see.
+ * - `"provider-executed"` — the model provider runs the tool on its own side. The
+ *   call never reaches this process.
+ * - `"hosted-mcp"` — the tool is a hosted MCP server's, and the write happens
+ *   server-side, past the boundary an adapter can bind at.
+ *
+ * The first one that matches is the category reported; a tool with no `execute` that
+ * is *also* provider-executed reads as `"no-execute"`, because that is the fact a
+ * host can check without knowing anything about the provider.
+ *
+ * ## Why a declaration, and why it does not make the tool safe
+ *
+ * A host that knows it cannot cover a tool may declare it. The declaration does not
+ * grant the tool anything: it converts a **wire-up refusal** into a **Docket record**
+ * — every proposal from that tool is filed `pending` with `blocked: { code:
+ * "coverage-refused", category, toolName }`, which AZ-4 says can never be decided and
+ * never executes. So the choice a host makes is not "refuse or allow"; it is "refuse
+ * at start-up, or refuse per proposal with the proposal on the record". The second is
+ * the more useful of the two when the host wants a person to see what an uncovered
+ * tool tried to do.
+ *
+ * What no declaration can do is cover a tool that opens its own connection and writes
+ * inside its body. GT-6 states that boundary as an honest limit rather than a rule an
+ * implementation can enforce.
+ *
+ * @packageDocumentation
+ */
+import type { TurnContext } from "../context.js";
+import type { BlockedMarker } from "../docket/entry.js";
+import type { FieldSchema, Operation } from "../ports.js";
+/**
+ * A tool as the host declares it, in the shape the gate needs to decide two things:
+ * whether it can be intercepted, and how its arguments become a proposal.
+ *
+ * The type parameters default to `never` and `unknown`, which makes the bare
+ * `ToolDefinition` a supertype of every concrete one — so
+ * {@link assessCoverage} and {@link declareUncovered} take any tool without a cast.
+ *
+ * `operation` is what a **write-capable** tool must supply: the function that turns a
+ * call's arguments into the {@link Operation} the Affidavit is sworn over. It is the
+ * host's declaration of what the tool is about to write, and it is required at
+ * wire-up rather than inferred, because nothing else in this package can know that
+ * `{ id, status }` is an update of a `Ticket` and not a search over one.
+ *
+ * `execute` takes the turn context as its second argument. A read tool is called
+ * with the same explicit context the gate was given (GT-2); nothing is ambient, at
+ * any depth of the call path. A write tool's `execute` is **never called by the
+ * gate** (GT-6) — see `wrap.ts`.
+ */
+export interface ToolDefinition<TArgs = never, TResult = unknown> {
+    /** The tool's name, as the model sees it and as a Docket row records it. */
+    readonly name: string;
+    /** What the tool does, in one line. */
+    readonly description: string;
+    /** The fields a proposal from this tool can carry, for the inference step. */
+    readonly inputSchema: FieldSchema;
+    /** The host's implementation. Called for a read tool; never for a write tool (GT-6). */
+    readonly execute?: (args: TArgs, ctx: TurnContext) => Promise<TResult> | TResult;
+    /** Whether a call to this tool would write. */
+    readonly writeCapable: boolean;
+    /** Who runs it. `"provider"` means the call never reaches this process. */
+    readonly executedBy?: "host" | "provider";
+    /** Whether the tool is a hosted MCP server's, writing server-side. */
+    readonly hostedMcp?: boolean;
+    /** How a call's arguments declare the write being proposed. Required for a write tool. */
+    readonly operation?: (args: TArgs) => Operation;
+    /** The host's own verb for the operation, e.g. `"WriteUpdate"`, carried onto the card. */
+    readonly operationLabel?: string;
+}
+/** Why a tool cannot be intercepted (CV-4). */
+export type UncoveredCategory = "no-execute" | "provider-executed" | "hosted-mcp";
+/** Every {@link UncoveredCategory}, in the order {@link assessCoverage} checks them. */
+export declare const UNCOVERED_CATEGORIES: readonly ["no-execute", "provider-executed", "hosted-mcp"];
+/** Whether `value` is one of the categories in {@link UNCOVERED_CATEGORIES}. */
+export declare function isUncoveredCategory(value: unknown): value is UncoveredCategory;
+/** What {@link assessCoverage} found. */
+export type CoverageAssessment = {
+    readonly covered: true;
+} | {
+    readonly covered: false;
+    readonly category: UncoveredCategory;
+};
+/**
+ * Whether the gate can intercept `tool`, and if not, which category it falls in.
+ *
+ * This asks only about **interception**, not about whether the tool matters: a read
+ * tool with no `execute` is reported uncovered too, because it is. What turns an
+ * uncovered assessment into a refusal is CV-4's other half —
+ * {@link ToolDefinition.writeCapable} — and that check lives in `wrap.ts`, where the
+ * refusal is raised.
+ */
+export declare function assessCoverage(tool: ToolDefinition): CoverageAssessment;
+/** One tool a host has declared it cannot cover. */
+export interface UncoveredDeclaration {
+    /** The tool's name — the key a later proposal is matched by. */
+    readonly toolName: string;
+    /** Why it cannot be covered. */
+    readonly category: UncoveredCategory;
+}
+/**
+ * The set of uncovered declarations a gate holds.
+ *
+ * One registry per gate, created by `createGate` and closed over by the pipeline —
+ * never a module-level map. Two gates in one process (two tenants' wirings, a test
+ * and the thing it tests) share nothing, which is the same reason GT-2 gives for the
+ * turn context: state that is reachable without being passed is state two callers
+ * can collide in.
+ */
+export interface CoverageRegistry {
+    /**
+     * Record that `toolName` cannot be covered.
+     *
+     * @throws RangeError if the tool was already declared under a different category —
+     *         a host contradicting itself about what a tool is, which is a programming
+     *         error rather than a refusal.
+     */
+    declare(toolName: string, category: UncoveredCategory): void;
+    /** The category `toolName` was declared under, or `null` if it was not declared. */
+    lookup(toolName: string): UncoveredCategory | null;
+    /** Every declaration, in the order they were made. */
+    declarations(): readonly UncoveredDeclaration[];
+}
+/** A fresh, empty {@link CoverageRegistry}. */
+export declare function createCoverageRegistry(): CoverageRegistry;
+/**
+ * Declare `tool` uncovered in `registry`, so that a later proposal from it is filed
+ * `blocked` rather than refused at wire-up (CV-4).
+ *
+ * The first parameter is the registry rather than the gate: `gate.ts` builds the
+ * registry and hands it to both `wrap` and the pipeline, and a function that took the
+ * gate would make this module import the module that imports it. `Gate.declareUncovered`
+ * is the surface a host calls; this is what it calls.
+ */
+export declare function declareUncovered(registry: CoverageRegistry, tool: Pick<ToolDefinition, "name">, category: UncoveredCategory): void;
+/** The AZ-4 marker a proposal from a declared-uncovered tool is filed with (CV-4). */
+export declare function coverageRefusedMarker(toolName: string, category: UncoveredCategory): BlockedMarker;
+//# sourceMappingURL=coverage.d.ts.map

package/dist/gate/coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../../src/gate/coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAM1D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,cAAc,CAAC,KAAK,GAAG,KAAK,EAAE,OAAO,GAAG,OAAO;IAC9D,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,wFAAwF;IACxF,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACjF,+CAA+C;IAC/C,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IAC1C,sEAAsE;IACtE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,0FAA0F;IAC1F,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,SAAS,CAAC;IAChD,0FAA0F;IAC1F,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAMD,+CAA+C;AAC/C,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,mBAAmB,GAAG,YAAY,CAAC;AAElF,wFAAwF;AACxF,eAAO,MAAM,oBAAoB,4DAIgB,CAAC;AAElD,gFAAgF;AAChF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAE9E;AAED,yCAAyC;AACzC,MAAM,MAAM,kBAAkB,GAC5B;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAEjG;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,cAAc,GAAG,kBAAkB,CAKvE;AAMD,oDAAoD;AACpD,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;CACtC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC7D,oFAAoF;IACpF,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAAC;IACnD,sDAAsD;IACtD,YAAY,IAAI,SAAS,oBAAoB,EAAE,CAAC;CACjD;AAED,+CAA+C;AAC/C,wBAAgB,sBAAsB,IAAI,gBAAgB,CA6BzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,gBAAgB,EAC1B,IAAI,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,EAClC,QAAQ,EAAE,iBAAiB,GAC1B,IAAI,CAEN;AAED,sFAAsF;AACtF,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,iBAAiB,GAC1B,aAAa,CAEf"}

package/dist/gate/coverage.js

@@ -0,0 +1,114 @@
+/**
+ * Coverage: which tools the gate can actually intercept, and what happens to the
+ * ones it cannot.
+ *
+ * **Rules served: CV-4** (a write-capable tool in an uncovered category is refused at
+ * wire-up, or — where wire-up cannot see it — marked `blocked` with code
+ * `coverage-refused` on the Docket; it is never silently allowed to write),
+ * **CV-1** (the refusal is at wire-up and there is no option that turns the gate off
+ * for a tool it covers), **AZ-4** (the blocked marker and its codes).
+ *
+ * ## The three categories
+ *
+ * A tool is *uncovered* when there is nothing for the gate to replace:
+ *
+ * - `"no-execute"` — the tool declares no `execute`. There is no function to stand in
+ *   front of; whatever writes, writes somewhere this package cannot see.
+ * - `"provider-executed"` — the model provider runs the tool on its own side. The
+ *   call never reaches this process.
+ * - `"hosted-mcp"` — the tool is a hosted MCP server's, and the write happens
+ *   server-side, past the boundary an adapter can bind at.
+ *
+ * The first one that matches is the category reported; a tool with no `execute` that
+ * is *also* provider-executed reads as `"no-execute"`, because that is the fact a
+ * host can check without knowing anything about the provider.
+ *
+ * ## Why a declaration, and why it does not make the tool safe
+ *
+ * A host that knows it cannot cover a tool may declare it. The declaration does not
+ * grant the tool anything: it converts a **wire-up refusal** into a **Docket record**
+ * — every proposal from that tool is filed `pending` with `blocked: { code:
+ * "coverage-refused", category, toolName }`, which AZ-4 says can never be decided and
+ * never executes. So the choice a host makes is not "refuse or allow"; it is "refuse
+ * at start-up, or refuse per proposal with the proposal on the record". The second is
+ * the more useful of the two when the host wants a person to see what an uncovered
+ * tool tried to do.
+ *
+ * What no declaration can do is cover a tool that opens its own connection and writes
+ * inside its body. GT-6 states that boundary as an honest limit rather than a rule an
+ * implementation can enforce.
+ *
+ * @packageDocumentation
+ */
+/** Every {@link UncoveredCategory}, in the order {@link assessCoverage} checks them. */
+export const UNCOVERED_CATEGORIES = [
+    "no-execute",
+    "provider-executed",
+    "hosted-mcp",
+];
+/** Whether `value` is one of the categories in {@link UNCOVERED_CATEGORIES}. */
+export function isUncoveredCategory(value) {
+    return typeof value === "string" && UNCOVERED_CATEGORIES.includes(value);
+}
+/**
+ * Whether the gate can intercept `tool`, and if not, which category it falls in.
+ *
+ * This asks only about **interception**, not about whether the tool matters: a read
+ * tool with no `execute` is reported uncovered too, because it is. What turns an
+ * uncovered assessment into a refusal is CV-4's other half —
+ * {@link ToolDefinition.writeCapable} — and that check lives in `wrap.ts`, where the
+ * refusal is raised.
+ */
+export function assessCoverage(tool) {
+    if (typeof tool.execute !== "function")
+        return { covered: false, category: "no-execute" };
+    if (tool.executedBy === "provider")
+        return { covered: false, category: "provider-executed" };
+    if (tool.hostedMcp === true)
+        return { covered: false, category: "hosted-mcp" };
+    return { covered: true };
+}
+/** A fresh, empty {@link CoverageRegistry}. */
+export function createCoverageRegistry() {
+    const declared = new Map();
+    return {
+        declare(toolName, category) {
+            if (toolName.trim() === "") {
+                throw new RangeError("CV-4: an uncovered declaration names a tool; the name was blank");
+            }
+            if (!isUncoveredCategory(category)) {
+                throw new RangeError(`CV-4: ${JSON.stringify(category)} is not an uncovered category; the three are ` +
+                    `${UNCOVERED_CATEGORIES.join(", ")}`);
+            }
+            const existing = declared.get(toolName);
+            if (existing !== undefined && existing !== category) {
+                throw new RangeError(`CV-4: tool ${JSON.stringify(toolName)} is already declared uncovered as ` +
+                    `${JSON.stringify(existing)}; it cannot also be ${JSON.stringify(category)}`);
+            }
+            declared.set(toolName, category);
+        },
+        lookup(toolName) {
+            return declared.get(toolName) ?? null;
+        },
+        declarations() {
+            return [...declared].map(([toolName, category]) => ({ toolName, category }));
+        },
+    };
+}
+/**
+ * Declare `tool` uncovered in `registry`, so that a later proposal from it is filed
+ * `blocked` rather than refused at wire-up (CV-4).
+ *
+ * The first parameter is the registry rather than the gate: `gate.ts` builds the
+ * registry and hands it to both `wrap` and the pipeline, and a function that took the
+ * gate would make this module import the module that imports it. `Gate.declareUncovered`
+ * is the surface a host calls; this is what it calls.
+ */
+export function declareUncovered(registry, tool, category) {
+    registry.declare(tool.name, category);
+}
+/** The AZ-4 marker a proposal from a declared-uncovered tool is filed with (CV-4). */
+export function coverageRefusedMarker(toolName, category) {
+    return { code: "coverage-refused", category, toolName };
+}
+//# sourceMappingURL=coverage.js.map

package/dist/gate/coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.js","sourceRoot":"","sources":["../../src/gate/coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAyDH,wFAAwF;AACxF,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,YAAY;IACZ,mBAAmB;IACnB,YAAY;CACmC,CAAC;AAElD,gFAAgF;AAChF,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,oBAA0C,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAClG,CAAC;AAMD;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,IAAoB;IACjD,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,UAAU;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAC;IAC1F,IAAI,IAAI,CAAC,UAAU,KAAK,UAAU;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAC7F,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAC;IAC/E,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC3B,CAAC;AAsCD,+CAA+C;AAC/C,MAAM,UAAU,sBAAsB;IACpC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA6B,CAAC;IACtD,OAAO;QACL,OAAO,CAAC,QAAgB,EAAE,QAA2B;YACnD,IAAI,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;gBAC3B,MAAM,IAAI,UAAU,CAAC,iEAAiE,CAAC,CAAC;YAC1F,CAAC;YACD,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACnC,MAAM,IAAI,UAAU,CAClB,SAAS,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,+CAA+C;oBAC9E,GAAG,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACvC,CAAC;YACJ,CAAC;YACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACxC,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;gBACpD,MAAM,IAAI,UAAU,CAClB,cAAc,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,oCAAoC;oBACxE,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,uBAAuB,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAC/E,CAAC;YACJ,CAAC;YACD,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QACnC,CAAC;QACD,MAAM,CAAC,QAAgB;YACrB,OAAO,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC;QACxC,CAAC;QACD,YAAY;YACV,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;QAC/E,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAA0B,EAC1B,IAAkC,EAClC,QAA2B;IAE3B,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AACxC,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,qBAAqB,CACnC,QAAgB,EAChB,QAA2B;IAE3B,OAAO,EAAE,IAAI,EAAE,kBAAkB,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AAC1D,CAAC"}

package/dist/gate/decide.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Decisions: who may make one, what it attests to, what it does to the row, and how
+ * a refused one is resubmitted.
+ *
+ * **Rules served: AZ-1** (every decided row carries an attestation record naming who
+ * agreed, when, and to which entry), **AZ-2** (tenant-scoped, fail-closed decision
+ * authorization, checked by the framework before any transition), **AZ-3** (what
+ * identity may attest what — a machine caller may never attest `member`), **AZ-4** (a
+ * blocked entry refuses every decision), **AZ-5** (the Docket is the sole record of
+ * approval authority: the only way to `executed` is a report against an approved,
+ * attested row), **AZ-6** (nothing here is conditional on a port, a model or a
+ * transport being available, so there is no degraded path that skips a check),
+ * **AZ-7** (the gate never performs the write — there is no executor port and no
+ * method that calls one), **DK-1** (the guarded compare-and-set, expiry as state with
+ * the late decision's amendments preserved, the execution outcome, resubmission
+ * lineage), **DK-2** (`null` clears, absent leaves untouched), **DK-5** (rehydration
+ * order), **AF-4** (an accepted amendment recomputes the three numbers), **PV-2** (an
+ * amended field's tag carries a `reviewer-act` binding naming the decision).
+ *
+ * ## The order the checks run in, and why it is this order
+ *
+ * 1. **No resolved principal → refused, before the store is touched.** AZ-2's
+ *    "fail closed, never *identity unknown, allow*" is not only about the answer; it
+ *    is about not doing any work on an entry for a caller who has not been
+ *    identified. A read that happened before the refusal is a read an attacker can
+ *    time.
+ * 2. **The entry is fetched inside the caller's tenant, and the row that comes back
+ *    is checked against it.** A row in another tenant is reported as
+ *    `entry-not-found`, exactly as an id that never existed — never "not authorized
+ *    for that tenant", which would be an oracle for guessing ids. The scope goes to
+ *    the store *and* the row's own `tenantId` is compared here, because AZ-2 makes
+ *    this the framework's check: a host store with a scope bug would otherwise fail
+ *    open with nothing above it noticing.
+ * 3. **The host's authorization port.** Its answer is the host's own — role,
+ *    ownership, separation of duties. A port that throws is a refusal.
+ * 4. **What the entry reads *now*.** Expiry is state (DK-1): a row past its deadline
+ *    reads `expired` whether or not the host's sweep has run, and a decision on it is
+ *    refused with the amendments it carried preserved for a resubmission — provided
+ *    the caller could have attested at all, because those values come back as a
+ *    person's act on the resubmission (PV-3).
+ * 5. **The attestation.** Built from the principal, and *only* from the principal:
+ *    there is no parameter through which a caller can name whose signature this is.
+ * 6. **The transition**, a guarded compare-and-set that is applied once or not at
+ *    all.
+ *
+ * ## Why there is no `execute`
+ *
+ * AZ-7 says no package in an implementation writes to a host's store, and the gate
+ * has no executor port to call. The path to `execution: "executed"` is
+ * {@link markExecuted} — the host's own executor telling the Docket what happened.
+ * That is also why a `service` principal is admitted there and refused as a decider
+ * here: reporting an outcome is a statement of fact about work the host did, and a
+ * decision is an act of authority a machine may not perform on a person's behalf
+ * (AZ-3).
+ *
+ * @packageDocumentation
+ */
+import type { Principal, TurnContext } from "../context.js";
+import type { Attestor, DocketEntry, ExecutionOutcome } from "../docket/entry.js";
+import type { SessionStore } from "../docket/store.js";
+import type { AmendmentMap } from "../model/amendments.js";
+import type { AuthorizationPort } from "../ports.js";
+import type { FiledEntry, PipelineDeps } from "./pipeline.js";
+/**
+ * What a reviewer decided.
+ *
+ * Amending is not a third kind: it is an approval carrying an
+ * {@link AmendmentMap} (DK-2). Modelling it as a separate verb would let an
+ * implementation record an amendment that approved nothing, and a reviewer who
+ * corrects a field has, by correcting it, said what they are prepared to approve.
+ *
+ * A rejection requires a reason and an approval does not, for the asymmetric reason
+ * that a person who declines a machine's proposal is the only one who knows why,
+ * whereas an approval's reason is the Affidavit.
+ */
+export type Decision = {
+    /** Approve the write, as proposed or as amended. */
+    readonly kind: "approve";
+    /** The reviewer's corrections. `null` under a key clears the field; an absent key leaves it untouched (DK-2). */
+    readonly amendments?: AmendmentMap;
+    /** Why, for the record. Optional: the Affidavit is the reason. */
+    readonly reason?: string;
+} | {
+    /** Refuse the write. */
+    readonly kind: "reject";
+    /** Why. Required — a refusal nobody explained teaches the host nothing. */
+    readonly reason: string;
+};
+/**
+ * What a host's executor reports back: the write happened, or it did not.
+ *
+ * `"unexecuted"` is excluded because it is the state a row is *filed* in, never a
+ * report — an executor that has nothing to say says nothing.
+ */
+export type ExecutionReport = Exclude<ExecutionOutcome, "unexecuted">;
+/** Everything the decision path needs from the host, assembled once by `createGate`. */
+export interface DecideDeps extends PipelineDeps {
+    /** Who may decide an entry (AZ-2). The gate has already refused the cases this port must not be asked about. */
+    readonly authorization: AuthorizationPort;
+    /** The rehydration surface (DK-5), or `null` when the host supplied none. */
+    readonly sessions: SessionStore | null;
+}
+/**
+ * Approve, amend or reject the entry `entryId` names, as `ctx.principal` (DK-1,
+ * AZ-1, AZ-2, AZ-3).
+ *
+ * @returns The row as it stands after the transition.
+ * @throws AffiantError `"decision-unauthorized"` when the context carries no
+ *         resolved principal, when the host's authorization port says no, or when a
+ *         machine caller with nothing to relay tries to attest (AZ-2, AZ-3);
+ *         `"entry-not-found"` when no entry with that id is visible in the caller's
+ *         tenant; `"decision-expired"` when the entry has passed its deadline — the
+ *         decision's amendments are preserved on the row first (DK-1);
+ *         `"decision-not-pending"` when it has already been decided or is blocked
+ *         (AZ-4); `"decision-lost-race"` when a competing decision won the guarded
+ *         compare-and-set.
+ * @throws RangeError when an amendment map holds `undefined` under a key, or names a
+ *         field the Affidavit does not propose. Neither is a refusal the gate hands
+ *         back to a caller: they are caller programming errors, and an `AffiantError`
+ *         code would invite a host to catch and continue.
+ */
+export declare function decide(entryId: string, decision: Decision, ctx: TurnContext, deps: DecideDeps): Promise<DocketEntry>;
+/**
+ * Record what the host's executor did with an approved write (DK-1, AZ-5, AZ-7).
+ *
+ * `status` stays `approved` — the approval happened and is not undone by a failed
+ * write; only `execution` and `executionDetail` move. This is the **only** public
+ * path to `execution: "executed"`, and the gate never calls an executor to reach it:
+ * a host reads its approved-and-unexecuted rows (DK-5), does the write itself, and
+ * says what happened.
+ *
+ * A `service` principal is admitted here and refused as a decider (AZ-3). The
+ * asymmetry is the point: reporting an outcome is a statement of fact about work the
+ * host performed, which a machine is the right party to make, while a decision is an
+ * act of authority that a machine may never make in a person's name. The tenant check
+ * and the host's authorization port still apply, so "which service may report on this
+ * entry" is still the host's answer and not an open door.
+ *
+ * **Reported once.** The execution transition is a guarded compare-and-set out of
+ * `"unexecuted"`, like every other transition on a row (DK-1): a second report is
+ * refused and the first stands. Overwriting would let an approved-and-committed row
+ * later read `failed` — an edit in place of a recorded fact (DK-4), and the loss of
+ * exactly the distinction DK-1 requires the row to keep. So a host that retries a
+ * write reports **once**, when it knows the outcome; the retries are the host's
+ * business (AZ-5), the outcome is the Docket's.
+ *
+ * @throws AffiantError `"decision-unauthorized"`, `"entry-not-found"`,
+ *         `"decision-not-pending"` when the row is not `approved`, or
+ *         `"execution-already-recorded"` when it already carries an outcome.
+ */
+export declare function markExecuted(entryId: string, outcome: ExecutionReport, detail: string | null, ctx: TurnContext, deps: DecideDeps): Promise<DocketEntry>;
+/**
+ * File the expired entry `entryId` names again, as a **new** entry whose lineage
+ * points back at it (DK-1).
+ *
+ * A resubmission is never a reopening. The superseded entry keeps its terminal state
+ * and gains a successor link, so the history reads forward (DK-4) and nothing that
+ * was once decided is quietly edited. The new proposal carries the same operation and
+ * the same sworn fields, with the amendments the refused late decision left on the
+ * row prefilled as values — each prefilled field tagged `UserStated` with a
+ * `reviewer-act` binding naming the superseded entry (PV-2), so a reader of the new
+ * card can see which values came from a person's earlier correction rather than from
+ * the machine.
+ *
+ * The whole pipeline runs again: the policy chain gets another say, the deadline is
+ * stamped afresh from that verdict (GT-4), and the substance gate applies (GT-3). A
+ * resubmission is a new proposal, not a replay of an old approval.
+ *
+ * @throws AffiantError `"decision-unauthorized"`, `"entry-not-found"`, or
+ *         `"decision-not-pending"` when the entry does not read `expired`.
+ * @throws RangeError when the preserved amendment map names a field the Affidavit
+ *         does not propose.
+ */
+export declare function resubmit(entryId: string, ctx: TurnContext, deps: DecideDeps): Promise<FiledEntry>;
+/** A human-verified session's attestation. The only kind a `member` principal makes. */
+export type MemberAttestation = Extract<Attestor, {
+    kind: "member";
+}>;
+/** A person's decision carried by a relay. The strongest kind a `service` principal can make. */
+export type RelayAttestation = Extract<Attestor, {
+    kind: "member-via-relay";
+}>;
+/**
+ * The strongest attestation `principal` can honestly make, or `null` when it can
+ * make none (AZ-1, AZ-3).
+ *
+ * A `member` principal attests `member`. A `service` principal carrying both a relay
+ * assertion and the person it speaks for attests `member-via-relay`, naming both — and
+ * that is the *only* thing it can attest. A `service` principal with nothing to relay
+ * attests nothing: it is a machine acting on its own behalf, and a machine cannot
+ * agree to a write in a person's name.
+ *
+ * **AZ-3 is in the overloads, not only in the body.** The signature for a `service`
+ * principal cannot return a `member` attestation — a compiler rejects the shortcut
+ * before a reviewer has to notice it — and this is the only function in the package
+ * that builds an attestation for a decision, so there is no second path to check.
+ * `standing-order` is not reachable from here at all: a policy verdict writes that
+ * one, in the same operation as the filing (AZ-1, GT-1 step 9).
+ */
+export declare function attestorOf(principal: Extract<Principal, {
+    kind: "member";
+}>): MemberAttestation;
+export declare function attestorOf(principal: Extract<Principal, {
+    kind: "service";
+}>): RelayAttestation | null;
+export declare function attestorOf(principal: Principal): Attestor | null;
+//# sourceMappingURL=decide.d.ts.map

package/dist/gate/decide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decide.d.ts","sourceRoot":"","sources":["../../src/gate/decide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,KAAK,EAAe,QAAQ,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE/F,OAAO,KAAK,EAAS,YAAY,EAAmB,MAAM,oBAAoB,CAAC;AAG/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAI3D,OAAO,KAAK,EAAE,iBAAiB,EAAa,MAAM,aAAa,CAAC;AAEhE,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAmC,MAAM,eAAe,CAAC;AAO/F;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,QAAQ,GAChB;IACE,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,iHAAiH;IACjH,QAAQ,CAAC,UAAU,CAAC,EAAE,YAAY,CAAC;IACnC,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B,GACD;IACE,wBAAwB;IACxB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEN;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,gBAAgB,EAAE,YAAY,CAAC,CAAC;AAEtE,wFAAwF;AACxF,MAAM,WAAW,UAAW,SAAQ,YAAY;IAC9C,gHAAgH;IAChH,QAAQ,CAAC,aAAa,EAAE,iBAAiB,CAAC;IAC1C,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;CACxC;AASD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,MAAM,CAC1B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,WAAW,CAAC,CAuItB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,WAAW,CAAC,CAgDtB;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,UAAU,CAAC,CA0BrB;AA6MD,wFAAwF;AACxF,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC,QAAQ,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,CAAC;AAEtE,iGAAiG;AACjG,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,QAAQ,EAAE;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,CAAC,CAAC;AAE/E;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,GAAG,iBAAiB,CAAC;AACjG,wBAAgB,UAAU,CACxB,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,GACjD,gBAAgB,GAAG,IAAI,CAAC;AAC3B,wBAAgB,UAAU,CAAC,SAAS,EAAE,SAAS,GAAG,QAAQ,GAAG,IAAI,CAAC"}