@affiant/core 0.1.0-alpha.0

package/dist/gate/pipeline.d.ts

@@ -0,0 +1,285 @@
+/**
+ * The gate pipeline: everything between a tool call and a Docket row, in the order
+ * the protocol fixes.
+ *
+ * **Rules served: GT-1** (the order itself), **GT-3** (runtime substance refusal),
+ * **GT-4** (TTL stamped from the policy result, after the chain; a re-file keeps the
+ * existing deadline), **PV-1** (confidence clamped, merge by confidence then
+ * determinism), **PV-3** (the inference step cannot mint `UserStated`), **AF-1**
+ * (every proposed field present, unknown provenance recorded as `Empty`), **AF-3**
+ * (create carries no previous values; update carries the key on every field),
+ * **AZ-1** (a Standing Order writes its attestation in the same operation as the
+ * filing), **AZ-4** (a requirement this version does not run is filed blocked),
+ * **CV-4** (a declared-uncovered tool's proposal is filed blocked), **SR-4** (the
+ * card names the protocol version it conforms to), **TL-1** (the events).
+ *
+ * ## The order, and why it is this order (GT-1)
+ *
+ * 1. **Turn context** arrives as a parameter. Nothing here reads a global, and the
+ *    accumulators below are function-local, so two conversations interleaved in one
+ *    isolate cannot see each other's fields (GT-2).
+ * 2. **Deterministic interceptors** first, because a value a host can look up is
+ *    better evidence than a value a model can guess, and running them first means the
+ *    merge in step 4 is comparing against something rather than filling a blank.
+ * 3. **One tool-free structured inference** against the *unmodified* turn. One,
+ *    because a second pass over a turn a previous pass has already been told about is
+ *    a model agreeing with itself. Tool-free, because a model that can call tools
+ *    while being asked what a person said can go and find out.
+ * 4. **Merge** (PV-1): higher confidence wins, ties toward the more deterministic
+ *    source, the loser kept in the chain so a card can show a reviewer that the model
+ *    and the system of record disagreed.
+ * 5. **Projection**, then the Affidavit is built (AF-1, AF-3, AF-2).
+ * 6. **Substance refusal** (GT-3) — *before* the policy chain. A proposal that swears
+ *    to nothing must not reach a policy that might approve it, and must not be filed,
+ *    counted or broadcast.
+ * 7. **Policy** (AZ-4, PV-4, GT-5).
+ * 8. **TTL** (GT-4) — *after* the policy, because the deadline is part of what the
+ *    policy decided, and a global default stamped before the chain is the
+ *    non-conformant shape the rule names.
+ * 9. **File** (DK-1), idempotent by entry id.
+ *
+ * ## Entry ids are derived, not minted
+ *
+ * The id is a SHA-256 over the tenant, the conversation, the tool name and the
+ * canonical form of the operation and its arguments, laid out as a UUID. So a retry
+ * of the same call in the same conversation is the *same* entry: `store.file` returns
+ * the row that is already there, with its **existing** `expiresAt` (GT-4), and the
+ * card the model gets back is the card a reviewer is already looking at. A random id
+ * would file a second row for a retried call and start a second clock, which is the
+ * shape GT-4 names as wrong.
+ *
+ * A resubmission adds the id of the entry it supersedes to that material, so it is a
+ * different entry from the one it replaces (DK-1) and resubmitting the same expired
+ * entry twice is still one row.
+ *
+ * @packageDocumentation
+ */
+import type { Affidavit as WireAffidavit, FieldPresentation } from "@affiant/contract";
+import type { TurnContext } from "../context.js";
+import type { BlockedMarker, DocketEntry } from "../docket/entry.js";
+import type { DocketStore } from "../docket/store.js";
+import type { AffidavitFieldKind, JsonValue } from "../model/affidavit.js";
+import type { AmendmentMap } from "../model/amendments.js";
+import type { ProvenanceChain } from "../model/provenance.js";
+import type { Clock, FieldInterceptor, FieldSchema, InferencePort, Operation, ProjectionPort, RiskScorer, TelemetryPort } from "../ports.js";
+import type { CoverageRegistry } from "./coverage.js";
+import type { ApprovalPolicy } from "./policy.js";
+/**
+ * The Evidence Card envelope: the entry a proposal was filed under, the sworn
+ * record, the deadline, and the presentation the core does not swear to.
+ *
+ * The split is the whole point. The canonical form a host's execution grant binds
+ * to is defined over the Affidavit and its accepted amendments and nothing else
+ * (SR-1), so anything that is a **rendering decision** — the sentences a reviewer
+ * reads, whether a person must confirm, the closed set an input offers, the mask
+ * an input applies, the host's own name for the operation — travels here, on the
+ * envelope, where changing it cannot invalidate a grant minted over evidence that
+ * did not change. This type stays
+ * assignable to `@affiant/contract`'s `EvidenceCardRequest`;
+ * `test/gate-types.test-d.ts` asserts that it does.
+ *
+ * The two confidence companions AF-2 requires a card to show are on the Affidavit
+ * itself and repeated here for one version, which is where the superseded
+ * `0.0.1-seed` wire carried them — so a consumer written against either shape
+ * finds them.
+ */
+export interface EvidenceCardRequest {
+    /** The protocol version this envelope conforms to (SR-4). */
+    readonly protocolVersion: string;
+    /** The Docket entry this card is filed under. */
+    readonly docketId: string;
+    /** The Affidavit awaiting a decision, in the wire shape. */
+    readonly affidavit: WireAffidavit;
+    /** When the review window closes — the entry's `expiresAt` (GT-4). */
+    readonly requiredBy: string;
+    /** The amendments already made on a superseded entry, or `null` for a first filing. */
+    readonly priorAmendments: AmendmentMap | null;
+    /**
+     * Minimum confidence over the non-`Empty` proposed fields; `null` when there are
+     * none (AF-2). The same number the Affidavit carries.
+     */
+    readonly populatedConfidence: number | null;
+    /**
+     * How many proposed fields are tagged `Empty` (AF-2). The same number the
+     * Affidavit carries. Without it a person approving a card sees an aggregate of
+     * `0` and cannot tell how many fields are empty or how good the populated ones
+     * are.
+     */
+    readonly emptyFieldCount: number;
+    /**
+     * Why no decision on this entry will be accepted, or `null` when it can be
+     * decided (AZ-4, CV-4). On the envelope so a reviewer surface can render it
+     * rather than inferring it from a warning string.
+     */
+    readonly blocked: BlockedMarker | null;
+    /**
+     * How a reviewer surface should render each field's input: one entry per field
+     * the host declared a hint for, naming a field the Affidavit carries. **Absent**
+     * when the host declared none — nothing swears to a hint, so a producer with
+     * nothing to say says nothing.
+     *
+     * The gate carries a hint and validates nothing against it: a proposed or
+     * amended value outside `allowedValues`, or not matching `pattern`, is still
+     * recorded, and a host that wants such a value refused enforces that in its own
+     * policy.
+     */
+    readonly presentation?: readonly FieldPresentation[];
+    /**
+     * Sentences a reviewer should see beside the record — the reason a policy gave,
+     * and the sentence a blocked entry shows. **Absent** when there are none.
+     *
+     * The machine-readable half of a blocked entry is
+     * {@link EvidenceCardRequest.blocked}, which a surface renders rather than
+     * parsing a string out of this array. A consumer never switches on the text of a
+     * warning.
+     */
+    readonly warnings?: readonly string[];
+    /**
+     * The host's own verb for the operation — `"WriteUpdate"`, `"Reprice"`,
+     * `"Onboard"`. **Absent** when the host named none.
+     *
+     * `affidavit.operationType` is the protocol's two-valued **shape**, so that a rule
+     * about shape stays a predicate a policy can test without knowing any host's
+     * vocabulary. The host's word for the same act travels here, beside it and never
+     * instead of it, so a reviewer surface can head the card with the term a person
+     * recognises. Presentation like the slots above it: nothing swears to it and it is
+     * no part of the canonical form (SR-1).
+     */
+    readonly hostOperation?: string;
+    /**
+     * Whether a person must confirm this write before it commits — the policy
+     * chain's verdict, not a property of the evidence.
+     *
+     * `false` on a blocked entry: a card carrying a marker that says no decision will
+     * be accepted must not also offer a reviewer surface an approve button that
+     * cannot work (AZ-4, CV-4).
+     */
+    readonly requiresConfirmation: boolean;
+}
+/** What the pipeline returns: the row as the store holds it, and the card for a reviewer. */
+export interface FiledEntry {
+    /** The Docket entry, as it reads now. */
+    readonly entry: DocketEntry;
+    /** `false` when this was a re-file of an id already on the Docket (GT-4, DK-1). */
+    readonly created: boolean;
+    /** The Evidence Card the host delivers. Built from the **stored** entry, so a re-file re-broadcasts the original deadline. */
+    readonly card: EvidenceCardRequest;
+}
+/**
+ * A field the host has already tagged, for the Sequence C path where a capture
+ * arrives with its provenance settled and there is nothing to infer.
+ *
+ * `provenance` absent means the host is saying "proposed, provenance unknown", which
+ * AF-1 records as an `Empty` tag at confidence `0` — and which the substance gate
+ * then refuses if it is the *only* thing the proposal carries (GT-3).
+ */
+export interface PreparedField {
+    /** The field's name. Must be one the operation proposes (AF-1). */
+    readonly name: string;
+    /** Rendering hint for the reviewer surface. */
+    readonly kind: AffidavitFieldKind;
+    /** The proposed value. */
+    readonly value: JsonValue;
+    /** Where the value came from, with its binding. */
+    readonly provenance?: ProvenanceChain;
+    /** Whether the target entity requires the field. Defaults to the schema, else `false`. */
+    readonly isMandatory?: boolean;
+}
+/**
+ * One proposal, in the shape both entry points produce: `wrap`'s gated `execute`
+ * builds one from a tool and its arguments, and `Gate.file` builds one from a host's
+ * {@link PreparedField} list.
+ *
+ * Every property is required and explicitly nullable rather than optional. The two
+ * that matter are exclusive in practice: `schema` non-null runs steps 2 to 4,
+ * `preparedFields` non-null skips them, and `gate.ts` refuses a proposal that supplies
+ * neither.
+ */
+export interface PipelineProposal {
+    /** The write being proposed. */
+    readonly operation: Operation;
+    /** The tool the proposal came from — the name a coverage declaration is keyed by (CV-4). */
+    readonly toolName: string;
+    /** The field schema the inference step works against, or `null` to skip inference. */
+    readonly schema: FieldSchema | null;
+    /**
+     * The call's arguments, part of the entry id's derivation, or `null` when the
+     * capture came from no call.
+     *
+     * A {@link JsonValue}: {@link deriveEntryId} canonicalises this, and a value with
+     * no canonical form is a caller bug a typed host should hear about from the
+     * compiler rather than from a `TypeError` on the first filing.
+     */
+    readonly args: JsonValue | null;
+    /** Host-tagged fields, or `null` to run interceptors and inference. */
+    readonly preparedFields: readonly PreparedField[] | null;
+    /** The host's own verb for the operation, carried onto the card. */
+    readonly operationLabel: string | null;
+    /**
+     * The entry this filing supersedes, or `null` for a first filing (DK-1).
+     *
+     * Set only by `resubmit`. It goes onto the new row's `lineage.supersedes` **and**
+     * into the entry id's derivation, which is what makes a resubmission a different
+     * entry from the one it replaces while keeping the id deterministic: resubmitting
+     * the same superseded entry twice derives the same id, so the second call is an
+     * idempotent replay rather than a second row.
+     */
+    readonly supersedes: string | null;
+    /**
+     * The amendments already made on the superseded entry, carried onto the card so a
+     * reviewer sees the corrections they are being asked to confirm (DK-2). `null` for
+     * a first filing.
+     */
+    readonly priorAmendments: AmendmentMap | null;
+}
+/** Everything the pipeline needs from the host, assembled once by `createGate`. */
+export interface PipelineDeps {
+    /** The Docket (DK-1). */
+    readonly store: DocketStore;
+    /** The host's structured inference (GT-1 step 3). */
+    readonly inference: InferencePort;
+    /** The host's previous-value lookup (AF-3). */
+    readonly projection: ProjectionPort;
+    /** The approval chain, in order (AZ-4). */
+    readonly policies: readonly ApprovalPolicy[];
+    /** Deterministic resolvers, in order (GT-1 step 2, PV-2). */
+    readonly interceptors: readonly FieldInterceptor[];
+    /** The host's risk function (GT-5). */
+    readonly riskScorer?: RiskScorer | undefined;
+    /** Where every instant on the record comes from. */
+    readonly clock: Clock;
+    /** Where the TL-1 events go. */
+    readonly telemetry: TelemetryPort;
+    /** The deadline applied when neither the verdict nor the policy names one (GT-4). */
+    readonly defaultTtlMs: number;
+    /** The tools the host declared it cannot cover (CV-4). */
+    readonly coverage: CoverageRegistry;
+}
+/**
+ * Run steps 2 through 9 for `proposal` in `ctx` and return the filed entry with its
+ * card.
+ *
+ * @throws AffiantError `"substance-refused"` when the proposal swears to nothing
+ *         (GT-3). Nothing is filed, nothing is broadcast, and the refusal is on the
+ *         telemetry port before the throw.
+ * @throws RangeError when a port hands back something that is not a JSON value, or
+ *         an interceptor claims a field the operation does not propose. Neither is a
+ *         refusal the gate hands back to a model: they are host programming errors,
+ *         and an `AffiantError` code would invite a host to catch and continue.
+ */
+export declare function runPipeline(proposal: PipelineProposal, ctx: TurnContext, deps: PipelineDeps): Promise<FiledEntry>;
+/**
+ * The entry id for this proposal: a SHA-256 over the tenant, the conversation, the
+ * tool and the canonical form of the operation and its arguments, laid out as a UUID.
+ *
+ * The layout sets the version nibble to `8` and the variant bits to `10`, which RFC
+ * 9562 reserves for exactly this — a UUID whose bits are a hash an application chose.
+ * The shape matters because `docketId` is a UUID string on the wire; the determinism
+ * matters because it is what makes a retried tool call a replay rather than a second
+ * review (GT-4, DK-1).
+ *
+ * @throws TypeError if `args` contains something with no canonical form — a function,
+ *         a symbol, a cycle. Tool arguments are JSON; anything else is a caller bug.
+ */
+export declare function deriveEntryId(ctx: TurnContext, proposal: Pick<PipelineProposal, "toolName" | "operation" | "args" | "supersedes">): Promise<string>;
+//# sourceMappingURL=pipeline.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/gate/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,OAAO,KAAK,EAAE,SAAS,IAAI,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEvF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAEV,aAAa,EACb,WAAW,EAGZ,MAAM,oBAAoB,CAAC;AAG5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,KAAK,EAGV,kBAAkB,EAClB,SAAS,EAEV,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,KAAK,EAAW,eAAe,EAAiB,MAAM,wBAAwB,CAAC;AAEtF,OAAO,KAAK,EACV,KAAK,EACL,gBAAgB,EAChB,WAAW,EAEX,aAAa,EACb,SAAS,EACT,cAAc,EACd,UAAU,EACV,aAAa,EAEd,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,aAAa,CAAC;AAOjE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,mBAAmB;IAClC,6DAA6D;IAC7D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,uFAAuF;IACvF,QAAQ,CAAC,eAAe,EAAE,YAAY,GAAG,IAAI,CAAC;IAC9C;;;OAGG;IACH,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IACvC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACrD;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;;;OAOG;IACH,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;CACxC;AAED,6FAA6F;AAC7F,MAAM,WAAW,UAAU;IACzB,yCAAyC;IACzC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,8HAA8H;IAC9H,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;CACpC;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,0BAA0B;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,mDAAmD;IACnD,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC;IACtC,0FAA0F;IAC1F,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gCAAgC;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sFAAsF;IACtF,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IACpC;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;IAChC,uEAAuE;IACvE,QAAQ,CAAC,cAAc,EAAE,SAAS,aAAa,EAAE,GAAG,IAAI,CAAC;IACzD,oEAAoE;IACpE,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,YAAY,GAAG,IAAI,CAAC;CAC/C;AAED,mFAAmF;AACnF,MAAM,WAAW,YAAY;IAC3B,yBAAyB;IACzB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,+CAA+C;IAC/C,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;IACpC,2CAA2C;IAC3C,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACnD,uCAAuC;IACvC,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IAC7C,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,gCAAgC;IAChC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,qFAAqF;IACrF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;CACrC;AAYD;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,gBAAgB,EAC1B,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,UAAU,CAAC,CAwOrB;AAgMD;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,IAAI,CAAC,gBAAgB,EAAE,UAAU,GAAG,WAAW,GAAG,MAAM,GAAG,YAAY,CAAC,GACjF,OAAO,CAAC,MAAM,CAAC,CAajB"}