@affiant/core 0.1.0-alpha.2 → 0.1.0-alpha.3

package/README.md

@@ -14,17 +14,16 @@ decision, and reports what happened; the gate never touches your database. Nothi
 this depends on which model you use, which database you write to, or how the card
 reaches the person — those are ports you supply.
 
-> **On npm at `0.1.0-alpha.1`**, under the `alpha` dist-tag and with a provenance
-> attestation, since 2026-09-10: `npm i @affiant/core@alpha`. `latest` and `alpha` both
-> point at `0.1.0-alpha.1`; the repository carries `0.1.0-alpha.2`, which goes with the
-> next dispatch. The condition for publishing was exact: a **public parity
+> **On npm at `0.1.0-alpha.3`**, under the `alpha` dist-tag and with a provenance
+> attestation, since 2026-09-18: `npm i @affiant/core@alpha`. The publish workflow moves
+> the `alpha` dist-tag and no other, so a bare `npm i @affiant/core` — which follows
+> `latest` — does not reach this release. The condition for publishing was exact: a **public parity
 > report** — the per-implementation list of conformance fixtures each implementation
 > does not yet pass — and a **green, merge-blocking TypeScript conformance driver**
-> running the shared fixture suite against this package. Both hold. The .NET report is read at the rulebook's
-> [`v0.1.3`](https://github.com/Sakwala/affiant-protocol/releases/tag/v0.1.3) tag; this repository's own
-> manifest is read at **the rulebook commit its pin names, ahead of that rulebook's `v0.2.0` tag**, which is
-> where a version's text lives until the tag is cut — see `packages/contract/protocol/PIN`. The
-> [.NET parity report](https://github.com/Sakwala/affiant-protocol/blob/v0.1.3/conformance/parity/dotnet-v0.1.json)
+> running the shared fixture suite against this package. Both hold, at the rulebook's
+> [`v0.2.0`](https://github.com/Sakwala/affiant-protocol/releases/tag/v0.2.0) tag, which is what
+> `packages/contract/protocol/PIN` pins and what both manifests are read at. The
+> [.NET parity report](https://github.com/Sakwala/affiant-protocol/blob/v0.2.0/conformance/parity/dotnet-v0.1.json)
 > is public, with its oracle run log alongside it under `conformance/results/`, and
 > this package's own [conformance parity manifest](../conformance-driver/conformance/parity/typescript-v0.2.json)
 > is green on Node, Bun and workerd, asserted by the `conformance` job that is
@@ -285,6 +284,119 @@ A decision that arrives late is refused as expired, and the amendments it carrie
 so `gate.resubmit` files a fresh entry that prefills what the person had already typed
 rather than making them type it twice (DK-1).
 
+## The read side: a row a queue already holds
+
+A filing hands you the Evidence Card for the entry it just filed. A review queue is the
+other direction: it lists rows hours or days later, and all it has is the row. Two pure
+producers build the envelopes from it — no store, no clock, no port, no network.
+
+```ts
+import { cardFor, decisionResultOf, isCallerError } from "@affiant/core";
+import type { DocketEntry, EvidenceCardRequest } from "@affiant/core";
+
+// A queue item: the row, the host's field schema for the tool that proposed it, and
+// the instant you are rendering at.
+const card: EvidenceCardRequest = cardFor(row, {
+  now: new Date().toISOString(),
+  schema, // the same FieldSchema the tool declares — optional
+  operationLabel: "Reprice", // your own verb for the operation — optional
+});
+
+if (card.requiresConfirmation) {
+  // Only then is a decision still being asked for.
+}
+
+// After the decision: the report, for your own client or your audit surface.
+try {
+  const result = decisionResultOf(row);
+  void result.outcome; // "approved" | "rejected" | "expired" | "resubmitted"
+} catch (error) {
+  if (isCallerError(error) && error.kind === "entry-not-decided") {
+    // Nobody has decided this row yet, and this function reads no clock.
+  } else {
+    throw error;
+  }
+}
+
+// A row that supersedes another needs that row: the reviewer's earlier corrections
+// live on it and nowhere else, so its absence is refused rather than read as `null`.
+const superseded: DocketEntry | null =
+  row.lineage.supersedes === null ? null : await gate.get(row.lineage.supersedes, ctx);
+const resubmissionCard = cardFor(row, {
+  now: new Date().toISOString(),
+  ...(superseded === null ? {} : { superseded }),
+});
+```
+
+What `cardFor` gives you, and what it does not:
+
+- **`requiresConfirmation` is `true` only for a `pending`, unblocked row that has not
+  passed its deadline at `now`** — the same reading of the deadline the stores and the
+  sweep use (DK-1, DK-5). A blocked row's card says why and never claims a confirmation
+  is awaited (AZ-4). Every other row still has a card; only this flag says whether a
+  decision is being asked for.
+- **No policy sentence.** A card built while filing carries the reason the policy chain
+  gave. The row records the chain's **verdict**, not its prose, so a card built from the
+  row carries the sentences the row itself determines — the blocked markers — and no
+  others.
+- **`presentation` and `hostOperation` are whatever this call passes.** They are your
+  rendering of a proposal rather than its sworn substance, so they are not on the record
+  (SR-1). Widen a picker's `allowedValues` and every queue item renders the new set,
+  including rows filed before the change; the row names the tool that proposed it (CV-4),
+  which is how you find the declaration to pass.
+- **`priorAmendments` comes from the Docket.** For a first filing it is what that row
+  preserved — the corrections a decision carried after the deadline had passed. For a row
+  that supersedes another it is the superseded row's, which you pass as `superseded`;
+  omitting it, passing the wrong row, passing one from another tenant, or passing one for
+  a row that supersedes nothing throws kind `superseded-entry-mismatch`.
+- **The card of a row that changed since filing differs from the filing's card.** The
+  card shows the amended Affidavit and the numbers recomputed over it once an amendment
+  has been accepted (AF-2, AF-4), and a row whose deadline has since passed asks for no
+  confirmation. Only for the row **as it was filed** is the card the one the filing
+  returned.
+
+What `decisionResultOf` gives you:
+
+- The outcome from the status, except that an expired row reads **`resubmitted`** once a
+  successor has superseded it.
+- **`attestation: null` and `execution: null` on anything but an approval.** The
+  envelope's `attestation` answers "who agreed", and a rejection and an expiry have no
+  answer (AZ-1) — even though the **row** of a rejection does name the person who
+  rejected it. The two documents answer different questions.
+- A `pending` row throws kind `entry-not-decided`. Whether it has passed its deadline is
+  read against an instant, and this function is given none: settle it with the sweep, or
+  read the row's status at the instant you mean.
+
+### Errors that are yours, not the gate's
+
+A refusal is something the gate decided about a proposal, and it carries an `ErrorCode`
+from the rulebook's registry. A mistake in your own code is not that. Four such mistakes
+now throw `AffiantCallerError` — a subclass of `RangeError`, so anything catching one
+today still catches it — with a stable `kind` and structured `details`:
+
+| `kind`                      | When                                                                                                                                                                                                         |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `amendment-unknown-field`   | An amendment names a field the Affidavit does not propose. It changes no state (DK-2), so you may catch it after `decide` rather than pre-check; the row stays decidable.                                    |
+| `turn-context-invalid`      | The turn context's `conversationId`, `tenantId` or `channel` is blank. Thrown at the top of the pipeline, before the interceptors and before your model is called (GT-1): nothing is filed and no port runs. |
+| `superseded-entry-mismatch` | `cardFor` was given the wrong superseded row, or none for a row that needs one, or one for a row that supersedes nothing.                                                                                    |
+| `entry-not-decided`         | `decisionResultOf` was given a `pending` row.                                                                                                                                                                |
+
+- **A `kind` is not an `ErrorCode`.** It is not in the rulebook's refusal registry and it
+  never crosses the wire as one. `isCallerError(value)` is the guard, and it answers
+  truthfully even across two loaded copies of this package.
+- **`kind` and `details` survive `JSON.stringify`; they do not survive
+  `structuredClone`.** They are own enumerable properties, so
+  `JSON.stringify(error)` reads `{"kind":…,"details":…,"name":"AffiantCallerError"}` —
+  enough to log or to send to your own client (`message` and `stack` are not enumerable
+  on any `Error`, so a JSON round trip is data and not an error, and `isCallerError`
+  reads `false` on it). `structuredClone` goes the other way: it carries an error's
+  `message`, `stack` and `cause` and drops every other own property, and the clone reads
+  `name: "Error"` — so a caller error does not cross a `postMessage` intact. Read `kind`
+  on the caught error, not on a copy of it.
+- **A blank `turn.messageId` is not refused**, and neither is a blank utterance or an
+  absent `turn`. Only the three identifiers above are read at the top of the pipeline,
+  and the set of inputs the gate refuses did not change when they moved there.
+
 ## What this package does not claim
 
 - **It swears to the field, not to the database.** An Affidavit is a record of what an

package/dist/errors.d.ts

@@ -150,4 +150,71 @@ export declare class AffiantError extends Error {
  * from {@link ERROR_CODES}.
  */
 export declare function isAffiantError(value: unknown): value is AffiantError;
+/**
+ * Which programming mistake a caller made, from the closed set this release names.
+ *
+ * A kind is **not** an {@link ErrorCode}. It is not in the protocol's refusal
+ * registry, it never appears in {@link ERROR_CODES}, and it never crosses the wire
+ * as one: the registry names gate refusals only, and the rulebook classes an
+ * amendment naming a field the Affidavit does not propose, or a verdict naming a
+ * requirement outside the four, as a language-level error rather than a refusal
+ * code. These kinds live in this package, for a host that wants to tell one of its
+ * own mistakes from another without reading an error message.
+ *
+ * - `amendment-unknown-field` — an amendment named a field the Affidavit does not
+ *   propose. The entry changes no state (DK-2).
+ * - `turn-context-invalid` — an identifier the turn context must carry was blank.
+ * - `superseded-entry-mismatch` — a card was asked for on a row that supersedes
+ *   another, without the superseded row, or with the wrong one.
+ * - `entry-not-decided` — a decision report was asked for on a row still `pending`.
+ */
+export type CallerErrorKind = "amendment-unknown-field" | "turn-context-invalid" | "superseded-entry-mismatch" | "entry-not-decided";
+/**
+ * Structured context attached to an {@link AffiantCallerError}: the field an
+ * amendment named, the entry it was made on, the identifier that was blank.
+ *
+ * Values are `unknown` because the useful details differ per kind, exactly as they
+ * do on {@link AffiantErrorDetails}. Never put a field value or an utterance in
+ * here — an error is not an audit record.
+ */
+export interface AffiantCallerErrorDetails {
+    readonly [key: string]: unknown;
+}
+/**
+ * A programming mistake in the calling code, told apart from the host's own bugs.
+ *
+ * This is **not a refusal**. A refusal is an {@link AffiantError} carrying an
+ * {@link ErrorCode} from the protocol's closed registry — something the gate decided
+ * about a proposal or a decision. This class is the other thing: an argument the
+ * caller could not legally have passed, which the rulebook calls a language-level
+ * error rather than a refusal code. It extends `RangeError`, so every host that
+ * already catches a `RangeError` from these call sites keeps working; what is new is
+ * that `kind` and `details` can be branched on instead of a message string.
+ *
+ * `kind` is not an `ErrorCode`, is not in the refusal registry, and is never sent as
+ * one. Use {@link isCallerError} rather than `instanceof` where two copies of this
+ * package may be loaded in one process.
+ */
+export declare class AffiantCallerError extends RangeError {
+    /** Which programming mistake was made. */
+    readonly kind: CallerErrorKind;
+    /** Structured context for the mistake. `{}` when the throwing site supplied none. */
+    readonly details: AffiantCallerErrorDetails;
+    /**
+     * @param kind    Which programming mistake was made.
+     * @param message A human-readable explanation. Defaults to the kind itself.
+     * @param details Structured context for the mistake.
+     */
+    constructor(kind: CallerErrorKind, message?: string, details?: AffiantCallerErrorDetails);
+}
+/**
+ * Whether `value` is an {@link AffiantCallerError}.
+ *
+ * `instanceof` first, then a structural check, for the same reason
+ * {@link isAffiantError} has one: a host can end up with two copies of this package
+ * in one process, and a `catch` that spans that boundary still has to give a true
+ * answer. The structural arm is deliberately narrow — an `Error` named
+ * `AffiantCallerError` carrying one of the kinds above.
+ */
+export declare function isCallerError(value: unknown): value is AffiantCallerError;
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,SAAS;IACpB;;;;;;;OAOG;;IAEH;;;;;;;OAOG;;IAEH;;;;OAIG;;IAEH;;;;OAIG;;IAEH,0EAA0E;;IAE1E;;;;OAIG;;IAEH;;;OAGG;;IAEH;;;;OAIG;;IAEH,kEAAkE;;IAElE;;;;;;;;;;;OAWG;;CAEK,CAAC;AAEX,+CAA+C;AAC/C,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAEnE;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,iPAWiB,CAAC;AAE1C,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAE9D;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED;;;;;;GAMG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,4BAA4B;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,qFAAqF;IACrF,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IAEtC;;;;OAIG;gBACS,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB;CAM7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAOpE"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,SAAS;IACpB;;;;;;;OAOG;;IAEH;;;;;;;OAOG;;IAEH;;;;OAIG;;IAEH;;;;OAIG;;IAEH,0EAA0E;;IAE1E;;;;OAIG;;IAEH;;;OAGG;;IAEH;;;;OAIG;;IAEH,kEAAkE;;IAElE;;;;;;;;;;;OAWG;;CAEK,CAAC;AAEX,+CAA+C;AAC/C,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAEnE;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,iPAWiB,CAAC;AAE1C,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAE9D;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED;;;;;;GAMG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,4BAA4B;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,qFAAqF;IACrF,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IAEtC;;;;OAIG;gBACS,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB;CAM7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAOpE;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,eAAe,GACvB,yBAAyB,GACzB,sBAAsB,GACtB,2BAA2B,GAC3B,mBAAmB,CAAC;AAexB;;;;;;;GAOG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,kBAAmB,SAAQ,UAAU;IAChD,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,qFAAqF;IACrF,QAAQ,CAAC,OAAO,EAAE,yBAAyB,CAAC;IAE5C;;;;OAIG;gBACS,IAAI,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,yBAAyB;CAMzF;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAOzE"}

package/dist/errors.js

@@ -161,4 +161,63 @@ export function isAffiantError(value) {
         value.name === "AffiantError" &&
         isErrorCode(value.code));
 }
+/** Every {@link CallerErrorKind}, as data the guard below can test against. */
+const CALLER_ERROR_KINDS = [
+    "amendment-unknown-field",
+    "turn-context-invalid",
+    "superseded-entry-mismatch",
+    "entry-not-decided",
+];
+/** Whether `value` is one of the kinds in {@link CallerErrorKind}. */
+function isCallerErrorKind(value) {
+    return typeof value === "string" && CALLER_ERROR_KINDS.includes(value);
+}
+/**
+ * A programming mistake in the calling code, told apart from the host's own bugs.
+ *
+ * This is **not a refusal**. A refusal is an {@link AffiantError} carrying an
+ * {@link ErrorCode} from the protocol's closed registry — something the gate decided
+ * about a proposal or a decision. This class is the other thing: an argument the
+ * caller could not legally have passed, which the rulebook calls a language-level
+ * error rather than a refusal code. It extends `RangeError`, so every host that
+ * already catches a `RangeError` from these call sites keeps working; what is new is
+ * that `kind` and `details` can be branched on instead of a message string.
+ *
+ * `kind` is not an `ErrorCode`, is not in the refusal registry, and is never sent as
+ * one. Use {@link isCallerError} rather than `instanceof` where two copies of this
+ * package may be loaded in one process.
+ */
+export class AffiantCallerError extends RangeError {
+    /** Which programming mistake was made. */
+    kind;
+    /** Structured context for the mistake. `{}` when the throwing site supplied none. */
+    details;
+    /**
+     * @param kind    Which programming mistake was made.
+     * @param message A human-readable explanation. Defaults to the kind itself.
+     * @param details Structured context for the mistake.
+     */
+    constructor(kind, message, details) {
+        super(message ?? kind);
+        this.name = "AffiantCallerError";
+        this.kind = kind;
+        this.details = details ?? {};
+    }
+}
+/**
+ * Whether `value` is an {@link AffiantCallerError}.
+ *
+ * `instanceof` first, then a structural check, for the same reason
+ * {@link isAffiantError} has one: a host can end up with two copies of this package
+ * in one process, and a `catch` that spans that boundary still has to give a true
+ * answer. The structural arm is deliberately narrow — an `Error` named
+ * `AffiantCallerError` carrying one of the kinds above.
+ */
+export function isCallerError(value) {
+    if (value instanceof AffiantCallerError)
+        return true;
+    return (value instanceof Error &&
+        value.name === "AffiantCallerError" &&
+        isCallerErrorKind(value.kind));
+}
 //# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/gate/card.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The Evidence Card for an entry that is already on the Docket.
+ *
+ * **Rules served: SR-1** (a host's rendering of a proposal lives on the card
+ * envelope and not on the sworn record), **DK-1 and DK-5** (a row that reads expired
+ * is never presented as one still awaiting a decision), **AZ-4 and CV-4** (a blocked
+ * entry's card says so and never claims a confirmation is being awaited), **AF-2 and
+ * AF-4** (the card shows the amended record and the numbers recomputed over it).
+ *
+ * A filing already returns a card, but a review queue lists entries long after they
+ * were filed and has only the row. {@link cardFor} is that producer: pure, reading
+ * no store, no clock and no port, and building through the same internal builder the
+ * filing path uses so the two cannot drift.
+ *
+ * Two things the row cannot supply, and which therefore come from the caller: the
+ * per-field rendering hints and the host's own verb for the operation. SR-1 puts
+ * both on the envelope rather than on the record, and the Docket entry schema is
+ * closed and has nowhere to keep them — so they are whatever the host passes on
+ * *this* call, not what it passed at filing. The host can look them up: the row
+ * records the tool that proposed it (CV-4), and the host holds that tool's
+ * declaration.
+ *
+ * One thing a card built here does not carry: the sentence a policy chain gave at
+ * filing. The row records the policy's verdict, not its prose, and re-running the
+ * chain now would evaluate a different moment.
+ *
+ * @packageDocumentation
+ */
+import type { DocketEntry } from "../docket/entry.js";
+import type { FieldSchema } from "../ports.js";
+import type { EvidenceCardRequest } from "./pipeline.js";
+/**
+ * What a card needs beside the row.
+ *
+ * Everything here except `now` is optional, and a card built with none of them is a
+ * complete card: it simply carries no rendering hints, no host verb, and — for a
+ * first filing — whatever the row itself preserved.
+ */
+export interface CardForOptions {
+    /**
+     * The instant to read the row's deadline against, in any form
+     * {@link readStatus} accepts — it measures the deadline with `instantMs`, which
+     * reads an instant with `Date.parse`, so an offset form is accepted as well as a
+     * UTC one. An instant that reader cannot read throws a plain `RangeError`.
+     *
+     * Required, and a parameter rather than a reading, because this package owns no
+     * clock: a card built from a row is built at a moment the caller knows and
+     * the function cannot. It is what decides whether a `pending` row is still
+     * awaiting a decision (DK-1).
+     */
+    readonly now: string;
+    /**
+     * The host's field schema for the operation that proposed this row — the source of
+     * the card's per-field rendering hints.
+     *
+     * Absent, the card carries no `presentation`. The hints are the host's rendering
+     * of the proposal and not its sworn substance (SR-1), so they are supplied here
+     * rather than read off the row: a host that later widens a picker's set serves the
+     * widened set for every entry, including ones filed before the change.
+     */
+    readonly schema?: FieldSchema;
+    /**
+     * The host's own verb for the operation — `"Onboard"`, `"Reprice"`.
+     *
+     * Absent, the card omits `hostOperation`, which the envelope allows.
+     */
+    readonly operationLabel?: string;
+    /**
+     * The entry this one supersedes, as `gate.get` returns it.
+     *
+     * **Required when the row supersedes another**, because a reviewer's earlier
+     * corrections live on that row and nowhere else, and a card that silently dropped
+     * them would still be a valid envelope and still be wrong. Passing it for a row
+     * that supersedes nothing, or passing the wrong row, is a caller error.
+     */
+    readonly superseded?: DocketEntry;
+}
+/**
+ * The Evidence Card for `entry`, as a reviewer surface should see it at `now`.
+ *
+ * Pure: no store, no clock, no port, no network. The same builder the filing path
+ * uses, so for the same row, the same `schema`, the same `operationLabel`, the same
+ * superseded row and an instant before the deadline, this returns the card the
+ * filing returned — except that it carries no policy sentence in `warnings`.
+ *
+ * Works for a row in any status. An approved row, a rejected row and an expired row
+ * all have cards; `requiresConfirmation` is the one field that says whether a
+ * decision is being asked for, and it is `true` only for a row that is `pending`, is
+ * not blocked, and has not passed its deadline at `now` (DK-1, DK-5, AZ-4).
+ *
+ * @throws AffiantCallerError of kind `superseded-entry-mismatch` when the row
+ *         supersedes another and `options.superseded` is missing, is a different
+ *         entry, or belongs to another tenant — or when it is supplied for a row
+ *         that supersedes nothing.
+ * @throws RangeError when `now` or the row's `expiresAt` is not a readable instant.
+ */
+export declare function cardFor(entry: DocketEntry, options: CardForOptions): EvidenceCardRequest;
+//# sourceMappingURL=card.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"card.d.ts","sourceRoot":"","sources":["../../src/gate/card.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAGzD;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,GAAG,mBAAmB,CAexF"}

package/dist/gate/card.js

@@ -0,0 +1,110 @@
+/**
+ * The Evidence Card for an entry that is already on the Docket.
+ *
+ * **Rules served: SR-1** (a host's rendering of a proposal lives on the card
+ * envelope and not on the sworn record), **DK-1 and DK-5** (a row that reads expired
+ * is never presented as one still awaiting a decision), **AZ-4 and CV-4** (a blocked
+ * entry's card says so and never claims a confirmation is being awaited), **AF-2 and
+ * AF-4** (the card shows the amended record and the numbers recomputed over it).
+ *
+ * A filing already returns a card, but a review queue lists entries long after they
+ * were filed and has only the row. {@link cardFor} is that producer: pure, reading
+ * no store, no clock and no port, and building through the same internal builder the
+ * filing path uses so the two cannot drift.
+ *
+ * Two things the row cannot supply, and which therefore come from the caller: the
+ * per-field rendering hints and the host's own verb for the operation. SR-1 puts
+ * both on the envelope rather than on the record, and the Docket entry schema is
+ * closed and has nowhere to keep them — so they are whatever the host passes on
+ * *this* call, not what it passed at filing. The host can look them up: the row
+ * records the tool that proposed it (CV-4), and the host holds that tool's
+ * declaration.
+ *
+ * One thing a card built here does not carry: the sentence a policy chain gave at
+ * filing. The row records the policy's verdict, not its prose, and re-running the
+ * chain now would evaluate a different moment.
+ *
+ * @packageDocumentation
+ */
+import { readStatus } from "../docket/entry.js";
+import { AffiantCallerError } from "../errors.js";
+import { buildCard } from "./pipeline.js";
+/**
+ * The Evidence Card for `entry`, as a reviewer surface should see it at `now`.
+ *
+ * Pure: no store, no clock, no port, no network. The same builder the filing path
+ * uses, so for the same row, the same `schema`, the same `operationLabel`, the same
+ * superseded row and an instant before the deadline, this returns the card the
+ * filing returned — except that it carries no policy sentence in `warnings`.
+ *
+ * Works for a row in any status. An approved row, a rejected row and an expired row
+ * all have cards; `requiresConfirmation` is the one field that says whether a
+ * decision is being asked for, and it is `true` only for a row that is `pending`, is
+ * not blocked, and has not passed its deadline at `now` (DK-1, DK-5, AZ-4).
+ *
+ * @throws AffiantCallerError of kind `superseded-entry-mismatch` when the row
+ *         supersedes another and `options.superseded` is missing, is a different
+ *         entry, or belongs to another tenant — or when it is supplied for a row
+ *         that supersedes nothing.
+ * @throws RangeError when `now` or the row's `expiresAt` is not a readable instant.
+ */
+export function cardFor(entry, options) {
+    return buildCard(entry, {
+        priorAmendments: priorAmendmentsFor(entry, options.superseded),
+        schema: options.schema ?? null,
+        operationLabel: options.operationLabel ?? null,
+        // The row records the policy's verdict, not the sentence it gave (SR-1 keeps
+        // prose off the record), and re-running the chain here would judge a different
+        // moment against a host risk function this function is not allowed to call.
+        policyReason: null,
+        // DK-5: a row that reads expired is never presented as pending, swept or not —
+        // so the deadline is measured with the reading the stores and the sweep use
+        // rather than with a second comparison written here. AZ-4: a blocked entry's
+        // card never claims a confirmation is being awaited.
+        requiresConfirmation: readStatus(entry, options.now) === "pending" && entry.blocked === null,
+    });
+}
+/**
+ * The amendments a reviewer already made, which the Docket holds on the row this
+ * entry replaced.
+ *
+ * A first filing answers from its own preserved map — the amendments a decision
+ * carried after the deadline had passed (DK-1). A resubmission answers from the row
+ * it supersedes, which is where the corrections that prefilled it were preserved,
+ * and which the caller must therefore hand over. The absence fails loudly rather
+ * than reading `null`: a card that quietly dropped a reviewer's earlier corrections
+ * validates against the envelope schema and is still wrong.
+ */
+function priorAmendmentsFor(entry, superseded) {
+    const supersedes = entry.lineage.supersedes;
+    if (supersedes === null) {
+        if (superseded !== undefined) {
+            throw new AffiantCallerError("superseded-entry-mismatch", `Docket entry ${JSON.stringify(entry.entryId)} supersedes no entry, so there is no ` +
+                `superseded row for its card to read prior amendments from; entry ` +
+                `${JSON.stringify(superseded.entryId)} was supplied`, { entryId: entry.entryId, supersedes: null, supplied: superseded.entryId });
+        }
+        return entry.preservedAmendments?.amendments ?? null;
+    }
+    if (superseded === undefined) {
+        throw new AffiantCallerError("superseded-entry-mismatch", `Docket entry ${JSON.stringify(entry.entryId)} supersedes entry ` +
+            `${JSON.stringify(supersedes)}, whose preserved amendments are the card's ` +
+            `priorAmendments; pass that entry as options.superseded`, { entryId: entry.entryId, supersedes, supplied: null });
+    }
+    if (superseded.entryId !== supersedes) {
+        throw new AffiantCallerError("superseded-entry-mismatch", `Docket entry ${JSON.stringify(entry.entryId)} supersedes entry ` +
+            `${JSON.stringify(supersedes)}, but options.superseded is entry ` +
+            `${JSON.stringify(superseded.entryId)}`, { entryId: entry.entryId, supersedes, supplied: superseded.entryId });
+    }
+    if (superseded.tenantId !== entry.tenantId) {
+        throw new AffiantCallerError("superseded-entry-mismatch", `Docket entry ${JSON.stringify(entry.entryId)} belongs to tenant ` +
+            `${JSON.stringify(entry.tenantId)} and options.superseded to tenant ` +
+            `${JSON.stringify(superseded.tenantId)}; a card reads no row from another tenant`, {
+            entryId: entry.entryId,
+            supersedes,
+            tenantId: entry.tenantId,
+            suppliedTenantId: superseded.tenantId,
+        });
+    }
+    return superseded.preservedAmendments?.amendments ?? null;
+}
+//# sourceMappingURL=card.js.map

package/dist/gate/card.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"card.js","sourceRoot":"","sources":["../../src/gate/card.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAIlD,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAiD1C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,OAAO,CAAC,KAAkB,EAAE,OAAuB;IACjE,OAAO,SAAS,CAAC,KAAK,EAAE;QACtB,eAAe,EAAE,kBAAkB,CAAC,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC;QAC9D,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,IAAI;QAC9B,cAAc,EAAE,OAAO,CAAC,cAAc,IAAI,IAAI;QAC9C,6EAA6E;QAC7E,+EAA+E;QAC/E,4EAA4E;QAC5E,YAAY,EAAE,IAAI;QAClB,+EAA+E;QAC/E,4EAA4E;QAC5E,6EAA6E;QAC7E,qDAAqD;QACrD,oBAAoB,EAAE,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,KAAK,IAAI;KAC7F,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,kBAAkB,CAAC,KAAkB,EAAE,UAAmC;IACjF,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC;IAE5C,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;QACxB,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,MAAM,IAAI,kBAAkB,CAC1B,2BAA2B,EAC3B,gBAAgB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,uCAAuC;gBAClF,mEAAmE;gBACnE,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,eAAe,EACtD,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,CAAC,OAAO,EAAE,CAC3E,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,CAAC,mBAAmB,EAAE,UAAU,IAAI,IAAI,CAAC;IACvD,CAAC;IAED,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,IAAI,kBAAkB,CAC1B,2BAA2B,EAC3B,gBAAgB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,oBAAoB;YAC/D,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,8CAA8C;YAC3E,wDAAwD,EAC1D,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,EAAE,CACvD,CAAC;IACJ,CAAC;IACD,IAAI,UAAU,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;QACtC,MAAM,IAAI,kBAAkB,CAC1B,2BAA2B,EAC3B,gBAAgB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,oBAAoB;YAC/D,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,oCAAoC;YACjE,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,EACzC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,CAAC,OAAO,EAAE,CACrE,CAAC;IACJ,CAAC;IACD,IAAI,UAAU,CAAC,QAAQ,KAAK,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC3C,MAAM,IAAI,kBAAkB,CAC1B,2BAA2B,EAC3B,gBAAgB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,qBAAqB;YAChE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,oCAAoC;YACrE,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,QAAQ,CAAC,2CAA2C,EACnF;YACE,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,UAAU;YACV,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,gBAAgB,EAAE,UAAU,CAAC,QAAQ;SACtC,CACF,CAAC;IACJ,CAAC;IAED,OAAO,UAAU,CAAC,mBAAmB,EAAE,UAAU,IAAI,IAAI,CAAC;AAC5D,CAAC"}

package/dist/gate/decide.js

@@ -56,7 +56,7 @@
  * @packageDocumentation
  */
 import { readStatus } from "../docket/entry.js";
-import { AffiantError } from "../errors.js";
+import { AffiantCallerError, AffiantError } from "../errors.js";
 import { applyAmendments, resolveAmendments } from "../model/amendments.js";
 import { mintTag, supersede } from "../model/provenance.js";
 import { runPipeline } from "./pipeline.js";
@@ -517,7 +517,7 @@ function refuseUnauthorized(entryId, ctx, path, reason, message, deps, now) {
 async function refuseExpired(entryId, scope, entry, amendments, principal, now, deps) {
     let preserved = false;
     if (amendments !== null && Object.keys(amendments).length > 0) {
-        requireAmendableFields(entry.affidavit, amendments);
+        requireAmendableFields(entry.affidavit, amendments, entryId);
         const attestor = attestorOf(principal);
         if (attestor !== null) {
             // The refused decision's **own** instant and principal (DK-1, PV-2): a
@@ -539,16 +539,20 @@ async function refuseExpired(entryId, scope, entry, amendments, principal, now,
 /**
  * Refuse an amendment map that names a field the Affidavit does not propose (DK-2).
  *
- * A `RangeError` and not an `AffiantError`, and the same message `applyAmendments`
- * raises: the {@link ErrorCode} registry names refusals the gate makes about a
- * proposal's substance or a decider's identity, and a field name that is not there is
- * a caller passing an index out of range.
+ * An {@link AffiantCallerError} — still a `RangeError`, and still the message
+ * `applyAmendments` raises: the {@link ErrorCode} registry names refusals the gate
+ * makes about a proposal's substance or a decider's identity, and a field name that
+ * is not there is a caller passing an index out of range. The `kind` is what lets a
+ * host answer its own client about it without reading the message.
+ *
+ * DK-2: nothing is written before this runs, so the row is untouched and a later
+ * valid decision on it still succeeds.
  */
-function requireAmendableFields(affidavit, map) {
+function requireAmendableFields(affidavit, map, entryId) {
     for (const resolved of resolveAmendments(map)) {
         if (!affidavit.fields.some((field) => field.name === resolved.name)) {
-            throw new RangeError(`amendment names field ${JSON.stringify(resolved.name)}, which this Affidavit does ` +
-                `not propose`);
+            throw new AffiantCallerError("amendment-unknown-field", `amendment names field ${JSON.stringify(resolved.name)}, which this Affidavit does ` +
+                `not propose`, { field: resolved.name, entryId });
         }
     }
 }