@affiant/core 0.1.0-alpha.0

package/dist/docket/store.d.ts

@@ -0,0 +1,387 @@
+/**
+ * The Docket store contract — what a store must do, stated so that the in-memory
+ * reference store and a production store are held to the same fixtures.
+ *
+ * **Rules served: DK-1** (idempotent filing, the guarded compare-and-set, expiry as
+ * queryable state, preserved amendments on a late decision, lineage), **DK-3** (a
+ * bounded, paged, host-scheduled sweep), **DK-4** (retention, purge and export are
+ * hooks the host drives, and a row reads forward), **DK-5** (rehydration order),
+ * **AZ-2** (every operation is tenant-scoped), **RT-2** (no unbounded operation).
+ *
+ * Three properties are worth reading the interface for.
+ *
+ * **Every operation is scoped.** There is no method that reaches a row by id alone.
+ * An entry id is unique *within a tenant*, and a lookup with the wrong tenant is not
+ * an error — it is a miss, indistinguishable from an id that does not exist.
+ * Anything else leaks the existence of another tenant's rows to whoever can guess an
+ * id, and AZ-2 exists because that check is the one hosts hand-roll and get wrong.
+ *
+ * **Every read applies expiry.** `get`, `listPending` and `rehydrate` report what a
+ * row *reads* as, not what it says: a `pending` entry past its deadline reads
+ * `expired` whether or not the host's sweep has run (DK-1). A store therefore needs
+ * to know the time, which is why it is built with a {@link Clock} rather than being
+ * handed an instant at every call — a store that took `now` as a parameter would let
+ * a caller answer the deadline question for it.
+ *
+ * **Every list is bounded.** No method returns "all of them". Lists are paged with
+ * an opaque cursor; the sweep and the retention hook take a limit and report whether
+ * more remain; export is an `AsyncIterable`. RT-2's envelope — a serverless isolate
+ * with no persistent process — has no room for a method that loads a tenant's
+ * Docket into memory.
+ *
+ * *Three divergences from the v0.1 design record, recorded deliberately.* The
+ * design's sketch of `transition` takes `(entryId, expected, patch)` and returns
+ * `entry | "lost-race" | "not-pending"`. First, every other method on the interface
+ * is scoped, and an unscoped transition would be the one door in the store through
+ * which a caller could move another tenant's row by guessing an id — exactly what
+ * AZ-2 closes; the signature here takes a {@link Scope} in the same position `get`
+ * does. Second, the sketch has no way to say *no such entry*: reporting a missing id
+ * as "not pending" would make a caller turn it into `decision-expired`, which is a
+ * different and misleading refusal, so {@link TransitionResult} carries a
+ * `"not-found"` arm as well. Third, the sketch's two refusal names describe the
+ * wrong halves: the arm it spells `"not-pending"` is the *expired* row, while the
+ * arm it spells `"lost-race"` is the row somebody else already decided — and a store
+ * implementer writing `UPDATE … WHERE status = 'pending'` will read "not pending" as
+ * the union of both. The names here say which is which: `"expired"` and
+ * `"already-decided"`.
+ *
+ * @packageDocumentation
+ */
+import type { Affidavit } from "../model/affidavit.js";
+import type { AmendmentMap } from "../model/amendments.js";
+import type { Attestation, DecisionRecord, DocketEntry, DocketStatus, ExecutionOutcome, PreservedAmendments } from "./entry.js";
+/**
+ * What a store operation is allowed to see.
+ *
+ * `tenantId` is mandatory: there is no cross-tenant read. `conversationId` narrows
+ * further, which is what a session surface asks for when it rehydrates one
+ * conversation rather than a whole tenant's Docket.
+ */
+export interface Scope {
+    /** The tenant. Mandatory — nothing in this interface reads across tenants. */
+    readonly tenantId: string;
+    /** One conversation within the tenant, when the caller wants only that (GT-2). */
+    readonly conversationId?: string;
+}
+/**
+ * Where to continue and how much to take.
+ *
+ * `cursor` is **opaque**: it is produced by a store, understood only by the same
+ * store, and bound to the list that produced it — feeding a `listPending` cursor to
+ * `export` is a caller error, not a silently different answer.
+ */
+export interface Page {
+    /** The `cursor` from the previous {@link PageResult}, or absent/`null` to start. */
+    readonly cursor?: string | null;
+    /** How many entries to return at most. */
+    readonly limit: number;
+}
+/** One page of a list. */
+export interface PageResult<T> {
+    /** The entries in this page, in filing order. */
+    readonly items: readonly T[];
+    /** Pass back as {@link Page.cursor} to continue, or `null` when the list is drained. */
+    readonly cursor: string | null;
+    /** Whether another page exists. `false` when `cursor` is `null`. */
+    readonly more: boolean;
+}
+/**
+ * What the host's retention job is allowed to remove (DK-4).
+ *
+ * Retention is a hook rather than a policy the framework holds an opinion about:
+ * how long an approval record must be kept is a legal question with a different
+ * answer in every jurisdiction the gate runs in, and a default would be wrong
+ * somewhere important.
+ */
+export interface RetentionPolicy {
+    /**
+     * Remove terminal entries whose terminal instant is strictly before this ISO 8601
+     * instant.
+     */
+    readonly olderThan: string;
+}
+/**
+ * What a transition out of `pending` writes.
+ *
+ * The patch is exactly the set of later facts a decision produces, and nothing
+ * else: it cannot touch the requirement, the deadline, the filing instant or the
+ * entry's own id. That is DK-4's read-forward property in the type — a row
+ * accumulates facts, it is never rewritten.
+ *
+ * {@link TransitionPatch.amendedAffidavit} is the one apparent exception, and it is
+ * not one: it is written *beside* the proposal, never over it. The row keeps
+ * `affidavit` as the agent proposed it and gains `amendedAffidavit` as the state the
+ * approval accepted, produced by `applyAmendments` from the row's own. That operation
+ * adds a `UserStated` tag carrying a `reviewer-act` binding on top of each amended
+ * field's chain and leaves the displaced tag in the chain's history (PV-2), so a
+ * reader can still see what the machine proposed under what the reviewer decided. A
+ * store cannot check that, so the rule is stated here and enforced by the gate, which
+ * is the only caller that builds one.
+ *
+ * `supersedes` is absent on purpose: it is fixed when an entry is filed and names
+ * the entry this one *replaces*, which cannot change afterwards. `supersededBy` is
+ * here because a caller may want to record a successor in the same write that closes
+ * a row, though the ordinary path writes it with
+ * {@link DocketStore.recordSupersession} on an already-terminal entry.
+ */
+export interface TransitionPatch {
+    /** The state the entry moves to. Never back to `pending`. */
+    readonly status: Exclude<DocketStatus, "pending">;
+    /**
+     * The execution outcome. Required to be `"unexecuted"` (the default) when `status`
+     * is `"approved"`, and `null` otherwise — a store refuses a patch that contradicts
+     * its own status (DK-1).
+     */
+    readonly execution?: ExecutionOutcome | null;
+    /** What the reviewer chose and why. Absent for a sweep, which nobody decided. */
+    readonly decision?: DecisionRecord | null;
+    /**
+     * The amendments the approval accepted. DK-2 holds inside the map: a `null` value
+     * clears the field, an absent key leaves it untouched.
+     */
+    readonly amendments?: AmendmentMap | null;
+    /**
+     * The accepted state an approval's amendments produced (AF-4).
+     *
+     * Absent leaves the row carrying its proposal alone, which is what a rejection, a
+     * sweep and an unamended approval all want. Present, it must be the result of
+     * applying {@link TransitionPatch.amendments} to *this row's* `affidavit` — the
+     * three confidence numbers recomputed over the amended fields, and each amended
+     * field's provenance the reviewer's act with the machine's tag preserved beneath
+     * it. It is written beside `affidavit`, which a store never overwrites (DK-4).
+     */
+    readonly amendedAffidavit?: Affidavit;
+    /** Who agreed (AZ-1). A decision without one is a decision nobody can be held to. */
+    readonly attestation?: Attestation | null;
+    /** When the row left `pending`. Defaults to the store's clock reading. */
+    readonly decidedAt?: string | null;
+    /** What the executor reported, when the caller already knows. */
+    readonly executionDetail?: string | null;
+    /** The successor link, for a caller closing and superseding a row in one write. */
+    readonly lineage?: {
+        readonly supersededBy?: string | null;
+    };
+}
+/**
+ * What a guarded compare-and-set returns.
+ *
+ * The two refusals are distinct because they mean different things to a caller and
+ * map to different error codes, and each is named after the state it describes.
+ * `"already-decided"` means **someone else decided this entry** — the row is
+ * `approved` or `rejected`, a second decision arrived, and DK-1 requires it be
+ * refused rather than applied twice or silently overwritten. `"expired"` means **the
+ * row passed its deadline**, whether or not a sweep has recorded that yet. A caller
+ * turns the first into `decision-lost-race` and the second into `decision-expired`,
+ * and the second is the one that must also preserve the amendments the late decision
+ * carried ({@link DocketStore.preserveAmendments}).
+ *
+ * The names are part of the contract, not an implementation detail: the in-memory
+ * store is the reference a Postgres store earns the name by passing the same fixtures
+ * as, and a name that describes the *other* arm's state — "not pending", which is
+ * true of both — is one a second implementer will get backwards.
+ *
+ * Between them the two cover every state a row can be in that is not `pending`, so
+ * a caller never has to re-read to find out which refusal it got. `"not-found"` is
+ * the third answer: no entry with that id is visible in the scope — which, for a
+ * caller in the wrong tenant, is the only answer they get (AZ-2).
+ */
+export type TransitionResult = DocketEntry | "not-found" | "already-decided" | "expired";
+/**
+ * The act a refused late decision was made by: its own instant and its own principal
+ * (DK-1, PV-2).
+ *
+ * The same two facts {@link PreservedAmendments} carries, named separately because
+ * this is what a caller passes in and that is what the row holds.
+ */
+export type PreservedAct = Omit<PreservedAmendments, "amendments">;
+/** What {@link DocketStore.preserveAmendments} returns. */
+export type PreserveAmendmentsResult = DocketEntry | "not-found" | "not-expired";
+/**
+ * What {@link DocketStore.recordExecution} returns.
+ *
+ * `"execution-already-recorded"` is the execution transition's half of DK-1's
+ * guarded compare-and-set: the row already carries an outcome, so this report is
+ * refused rather than written over the first one. It is a different answer from
+ * `"not-approved"` — that row was never approved and has no authorised write behind
+ * it at all, while this one is approved and already has its outcome on the record.
+ */
+export type RecordExecutionResult = DocketEntry | "not-found" | "not-approved" | "execution-already-recorded";
+/** What {@link DocketStore.recordSupersession} returns. */
+export type RecordSupersessionResult = DocketEntry | "not-found" | "not-terminal";
+/**
+ * The durable record of every proposed write and everything that happened to it.
+ *
+ * A store is the only thing in the framework that remembers, so it is also the only
+ * place the DK rules can be enforced rather than merely documented: the
+ * idempotent file, the guarded transition, the deadline applied on read, the bounded
+ * sweep and the append-only later facts are all properties of *this* interface. A
+ * host that swaps the in-memory reference store for Postgres inherits them by
+ * passing the same fixtures, not by re-reading the rulebook.
+ */
+export interface DocketStore {
+    /**
+     * File `entry`, or return the one already filed under its id (DK-1).
+     *
+     * Idempotent by `entryId` within the tenant, and idempotent in the strong sense:
+     * a re-file is **never** an error and **never** overwrites. It returns the stored
+     * entry as it stands, `created: false`, keeping its **existing** `expiresAt` — a
+     * re-file that refreshed the deadline would let a retrying agent hold a card open
+     * indefinitely, which is the .NET behaviour GT-4 corrects.
+     */
+    file(entry: DocketEntry): Promise<{
+        entry: DocketEntry;
+        created: boolean;
+    }>;
+    /**
+     * The entry, with expiry applied (DK-1), or `null`.
+     *
+     * `null` covers both "no such id" and "not in this scope". A caller outside the
+     * tenant learns nothing about whether the id exists.
+     */
+    get(entryId: string, scope: Scope): Promise<DocketEntry | null>;
+    /**
+     * Move an entry out of `pending`, if it is still `pending` (DK-1).
+     *
+     * A guarded compare-and-set: the read of the current state and the write of the
+     * new one happen with no interleaving point between them, so of two decisions that
+     * race, exactly one is applied and the other is refused. `expected` is `"pending"`
+     * and only `"pending"` — nothing else in the state machine has a transition out of
+     * it.
+     */
+    transition(entryId: string, scope: Scope, expected: "pending", patch: TransitionPatch): Promise<TransitionResult>;
+    /**
+     * Record the amendments a decision carried after the entry had already expired, so
+     * a resubmission can prefill them (DK-1).
+     *
+     * This is the one write that applies to a row the transition guard refused, and it
+     * is a separate method for that reason: folding it into `transition` would make a
+     * refused compare-and-set write to the row, and "applied once or not at all" is
+     * exactly the property DK-1's fixture asserts. Under DK-4 this is an appended
+     * later fact on a terminal row, not an edit of a recorded decision — it touches
+     * `amendments` and nothing else, never `status`, `decision` or `attestation`.
+     *
+     * `act` is the refused decision's **own** instant and principal, not the store's
+     * clock and not the row's deadline. A resubmission prefills these values as a
+     * person's correction and binds each prefilled field's tag to that act (PV-2), so
+     * a record that dated them to the sweep would place the correction at a moment
+     * nobody typed anything.
+     *
+     * Returns `"not-expired"` when the entry does not read `expired`; a caller that
+     * gets it has a bug, because a decision that was not refused as expired has no
+     * amendments to preserve.
+     */
+    preserveAmendments(entryId: string, scope: Scope, amendments: AmendmentMap, act: PreservedAct): Promise<PreserveAmendmentsResult>;
+    /**
+     * Record what the host's executor reported for an approved entry, **once**
+     * (DK-1, DK-4).
+     *
+     * `status` stays `approved`; only `execution` and `executionDetail` move. The
+     * framework never performs the write (AZ-7) — it records what the host says
+     * happened, so that an approved-but-failed write is distinguishable from an
+     * approved-and-committed one on the row.
+     *
+     * **A guarded compare-and-set, exactly like {@link DocketStore.transition}.**
+     * `expected` is `"unexecuted"` and only `"unexecuted"`: the execution transition
+     * runs once, out of the state a row is approved in, and a second report is refused
+     * with `"execution-already-recorded"` rather than written on top. Without the
+     * guard an `executed` row could be flipped to `failed` by a later caller — an edit
+     * in place of a recorded fact, which DK-4 forbids, leaving an approved-and-
+     * committed write indistinguishable from an approved-but-failed one, which DK-1
+     * forbids.
+     *
+     * The consequence for a host is one sentence: **a host that retries a write
+     * reports once, when it knows the outcome.** AZ-5 already says an outbox is a
+     * retry of an already-attested write and never a second authorization path; this
+     * is the same statement about the record — the retries are the host's business,
+     * the outcome is the Docket's.
+     *
+     * Returns `"not-approved"` for any row that is not `approved`, and
+     * `"execution-already-recorded"` for an approved row whose `execution` has already
+     * moved off `"unexecuted"`.
+     */
+    recordExecution(entryId: string, scope: Scope, outcome: Exclude<ExecutionOutcome, "unexecuted">, detail: string | null, expected: "unexecuted"): Promise<RecordExecutionResult>;
+    /**
+     * Record that a terminal entry has been resubmitted as `supersededBy` (DK-1).
+     *
+     * The superseded entry keeps its terminal state; only the successor link is added.
+     * A resubmission is a new entry, never a reopened one, which is what lets the
+     * history read forward (DK-4).
+     *
+     * Returns `"not-terminal"` for a row that still reads `pending`.
+     */
+    recordSupersession(entryId: string, scope: Scope, supersededBy: string): Promise<RecordSupersessionResult>;
+    /** Entries that read `pending` right now, in filing order, paged. */
+    listPending(scope: Scope, page: Page): Promise<PageResult<DocketEntry>>;
+    /**
+     * Entries that are `approved` and still `unexecuted`, in filing order, paged.
+     *
+     * The host's executor reads this: an approved write nobody has reported on is work
+     * outstanding, and after a restart it is the only record that the work exists.
+     */
+    listApprovedUnexecuted(scope: Scope, page: Page): Promise<PageResult<DocketEntry>>;
+    /**
+     * Mark at most `limit` entries that are due at `now` as `expired`, in filing order
+     * (DK-3).
+     *
+     * The host schedules this; the core owns no timer. The sweep makes the state
+     * durable and gives the host a list to notify on — it does not *cause* expiry,
+     * which every read already applies (DK-1). `more` says whether another call would
+     * find more, so a host drains the queue in bounded steps rather than in one
+     * unbounded pass.
+     */
+    expireDue(now: string, scope: Scope, limit: number): Promise<{
+        expired: string[];
+        more: boolean;
+    }>;
+    /**
+     * Remove at most `limit` terminal entries older than `policy.olderThan` (DK-4).
+     *
+     * Each call shrinks the eligible set, so a host drains retention by calling until
+     * `more` is `false` — the same bounded-step shape as the sweep, and for the same
+     * RT-2 reason.
+     */
+    retention(policy: RetentionPolicy, scope: Scope, limit: number): Promise<{
+        removed: number;
+        more: boolean;
+    }>;
+    /**
+     * Remove everything belonging to `tenantId` (DK-4).
+     *
+     * Unbounded by design and by necessity: a tenant asking for their data to be
+     * deleted is asking for all of it, and a partial purge is not a purge. It is the
+     * one operation that is not paged, and the only one that takes a tenant id rather
+     * than a {@link Scope} — there is no such thing as purging half a tenant.
+     */
+    purge(tenantId: string): Promise<{
+        removed: number;
+    }>;
+    /**
+     * Every entry in `scope`, in filing order, streamed (DK-4).
+     *
+     * An `AsyncIterable` rather than an array so a large Docket never has to fit in
+     * memory (RT-2). The portable document shape a host would export *to* is reserved
+     * for protocol v0.2; this yields the rows.
+     */
+    export(scope: Scope): AsyncIterable<DocketEntry>;
+}
+/**
+ * What a reconnecting client needs to see, in the order DK-5 fixes.
+ *
+ * **`pending` entries first, then `approved` and `unexecuted`**, each in filing
+ * order. The order is a rule rather than a preference because the two groups ask
+ * different things of the person reconnecting: the first still needs a decision, the
+ * second still needs execution, and a client that showed them interleaved would put
+ * work that is already agreed in front of work that is still blocked on the reader.
+ */
+export interface SessionStore {
+    /**
+     * One page of the rehydration sequence: everything that reads `pending`, then
+     * everything `approved` and `unexecuted`, each in filing order.
+     *
+     * Paged like every other list (RT-2). The cursor carries the position *within the
+     * sequence*, so a page boundary that falls between the two groups resumes at the
+     * start of the second rather than restarting the first.
+     */
+    rehydrate(scope: Scope, page: Page): Promise<PageResult<DocketEntry>>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/docket/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/docket/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAMpB;;;;;;GAMG;AACH,MAAM,WAAW,KAAK;IACpB,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kFAAkF;IAClF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,IAAI;IACnB,oFAAoF;IACpF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,0BAA0B;AAC1B,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IAC7B,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;IAClD;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC7C,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IAC1C;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAC1C;;;;;;;;;OASG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,CAAC;IACtC,qFAAqF;IACrF,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC1C,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,iEAAiE;IACjE,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,mFAAmF;IACnF,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CAC9D;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,WAAW,GAAG,iBAAiB,GAAG,SAAS,CAAC;AAEzF;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,mBAAmB,EAAE,YAAY,CAAC,CAAC;AAEnE,2DAA2D;AAC3D,MAAM,MAAM,wBAAwB,GAAG,WAAW,GAAG,WAAW,GAAG,aAAa,CAAC;AAEjF;;;;;;;;GAQG;AACH,MAAM,MAAM,qBAAqB,GAC/B,WAAW,GAAG,WAAW,GAAG,cAAc,GAAG,4BAA4B,CAAC;AAE5E,2DAA2D;AAC3D,MAAM,MAAM,wBAAwB,GAAG,WAAW,GAAG,WAAW,GAAG,cAAc,CAAC;AAMlF;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;;OAQG;IACH,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAE5E;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAEhE;;;;;;;;OAQG;IACH,UAAU,CACR,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,SAAS,EACnB,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAE7B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,kBAAkB,CAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,KAAK,EACZ,UAAU,EAAE,YAAY,EACxB,GAAG,EAAE,YAAY,GAChB,OAAO,CAAC,wBAAwB,CAAC,CAAC;IAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,eAAe,CACb,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,OAAO,CAAC,gBAAgB,EAAE,YAAY,CAAC,EAChD,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,QAAQ,EAAE,YAAY,GACrB,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAElC;;;;;;;;OAQG;IACH,kBAAkB,CAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,KAAK,EACZ,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,wBAAwB,CAAC,CAAC;IAErC,qEAAqE;IACrE,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC;IAExE;;;;;OAKG;IACH,sBAAsB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC;IAEnF;;;;;;;;;OASG;IACH,SAAS,CACP,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAEjD;;;;;;OAMG;IACH,SAAS,CACP,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAE/C;;;;;;;OAOG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEtD;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;CAClD;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC;CACvE"}

package/dist/docket/store.js

@@ -0,0 +1,51 @@
+/**
+ * The Docket store contract — what a store must do, stated so that the in-memory
+ * reference store and a production store are held to the same fixtures.
+ *
+ * **Rules served: DK-1** (idempotent filing, the guarded compare-and-set, expiry as
+ * queryable state, preserved amendments on a late decision, lineage), **DK-3** (a
+ * bounded, paged, host-scheduled sweep), **DK-4** (retention, purge and export are
+ * hooks the host drives, and a row reads forward), **DK-5** (rehydration order),
+ * **AZ-2** (every operation is tenant-scoped), **RT-2** (no unbounded operation).
+ *
+ * Three properties are worth reading the interface for.
+ *
+ * **Every operation is scoped.** There is no method that reaches a row by id alone.
+ * An entry id is unique *within a tenant*, and a lookup with the wrong tenant is not
+ * an error — it is a miss, indistinguishable from an id that does not exist.
+ * Anything else leaks the existence of another tenant's rows to whoever can guess an
+ * id, and AZ-2 exists because that check is the one hosts hand-roll and get wrong.
+ *
+ * **Every read applies expiry.** `get`, `listPending` and `rehydrate` report what a
+ * row *reads* as, not what it says: a `pending` entry past its deadline reads
+ * `expired` whether or not the host's sweep has run (DK-1). A store therefore needs
+ * to know the time, which is why it is built with a {@link Clock} rather than being
+ * handed an instant at every call — a store that took `now` as a parameter would let
+ * a caller answer the deadline question for it.
+ *
+ * **Every list is bounded.** No method returns "all of them". Lists are paged with
+ * an opaque cursor; the sweep and the retention hook take a limit and report whether
+ * more remain; export is an `AsyncIterable`. RT-2's envelope — a serverless isolate
+ * with no persistent process — has no room for a method that loads a tenant's
+ * Docket into memory.
+ *
+ * *Three divergences from the v0.1 design record, recorded deliberately.* The
+ * design's sketch of `transition` takes `(entryId, expected, patch)` and returns
+ * `entry | "lost-race" | "not-pending"`. First, every other method on the interface
+ * is scoped, and an unscoped transition would be the one door in the store through
+ * which a caller could move another tenant's row by guessing an id — exactly what
+ * AZ-2 closes; the signature here takes a {@link Scope} in the same position `get`
+ * does. Second, the sketch has no way to say *no such entry*: reporting a missing id
+ * as "not pending" would make a caller turn it into `decision-expired`, which is a
+ * different and misleading refusal, so {@link TransitionResult} carries a
+ * `"not-found"` arm as well. Third, the sketch's two refusal names describe the
+ * wrong halves: the arm it spells `"not-pending"` is the *expired* row, while the
+ * arm it spells `"lost-race"` is the row somebody else already decided — and a store
+ * implementer writing `UPDATE … WHERE status = 'pending'` will read "not pending" as
+ * the union of both. The names here say which is which: `"expired"` and
+ * `"already-decided"`.
+ *
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=store.js.map

package/dist/docket/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/docket/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG"}

package/dist/errors.d.ts

@@ -0,0 +1,153 @@
+/**
+ * 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 declare 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.
+     */
+    readonly "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.
+     */
+    readonly "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).
+     */
+    readonly "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).
+     */
+    readonly "decision-unauthorized": "decision-unauthorized";
+    /** A decision was made on an entry that is no longer `pending` (DK-1). */
+    readonly "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).
+     */
+    readonly "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).
+     */
+    readonly "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).
+     */
+    readonly "wireup-invalid": "wireup-invalid";
+    /** No entry with that id is visible in the given scope (DK-1). */
+    readonly "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.
+     */
+    readonly "execution-already-recorded": "execution-already-recorded";
+};
+/** One of the reasons in {@link ErrorCode}. */
+export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+/**
+ * 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 declare const ERROR_CODES: readonly ["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 declare function isErrorCode(value: unknown): value is ErrorCode;
+/**
+ * Structured context attached to an {@link AffiantError}: the entry id, the tool
+ * name, the policy that produced a verdict — whatever the throwing site can name.
+ *
+ * Values are `unknown` because the useful details differ per code. Callers narrow;
+ * loggers stringify. Never put a field value or an utterance in here — an error is
+ * not an audit record, and the audit record is the Affidavit.
+ */
+export interface AffiantErrorDetails {
+    readonly [key: string]: unknown;
+}
+/**
+ * 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 declare class AffiantError extends Error {
+    /** Why the gate refused. */
+    readonly code: ErrorCode;
+    /** Structured context for the refusal. `{}` when the throwing site supplied none. */
+    readonly details: AffiantErrorDetails;
+    /**
+     * @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: ErrorCode, message?: string, details?: AffiantErrorDetails);
+}
+/**
+ * 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 declare function isAffiantError(value: unknown): value is AffiantError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +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"}