@affiant/core 0.1.0-alpha.0

package/dist/docket/entry.js

@@ -0,0 +1,155 @@
+/**
+ * The Docket entry — the row every proposed write becomes, and the only record of
+ * approval authority the framework recognises.
+ *
+ * **Rules served: DK-1** (the review-outcome state machine, expiry as queryable
+ * state, lineage), **AZ-1** (the attestation record and its three attestor kinds),
+ * **AZ-4** (requirement levels and the `blocked` marker), **DK-4** (a row reads
+ * forward: later facts are appended, a recorded decision is never edited).
+ *
+ * DK-1 in one sentence: *`pending` goes to exactly one of `approved`, `rejected`
+ * or `expired`; an `approved` row carries an execution outcome so an
+ * approved-but-failed write is distinguishable from an approved-and-committed one;
+ * every transition out of `pending` is a guarded compare-and-set; and an entry past
+ * its expiry reads `expired` whether or not any sweep has run.*
+ *
+ * The last clause is why {@link readStatus} exists and why nothing in this package
+ * schedules a timer. Expiry is **state**, not an event: a host that never runs a
+ * sweep still cannot decide an expired entry, because every read applies the
+ * deadline. The sweep ({@link DocketStore.expireDue}) exists to make the state
+ * durable and to drive notifications, not to make it true.
+ *
+ * @packageDocumentation
+ */
+import { PROTOCOL_VERSION } from "@affiant/contract";
+import { isDue, requireInstant } from "./expiry.js";
+/** Every {@link DocketStatus}, pinned as data so a runtime check and a fixture read the same list. */
+export const DOCKET_STATUSES = [
+    "pending",
+    "approved",
+    "rejected",
+    "expired",
+];
+/** Every {@link ExecutionOutcome}, in the order a row moves through them. */
+export const EXECUTION_OUTCOMES = [
+    "unexecuted",
+    "executed",
+    "failed",
+];
+/**
+ * Whether `status` is terminal — everything except `pending`.
+ *
+ * `approved` counts as terminal for the *review*, which is what this predicate is
+ * about; whether the write has been executed is {@link DocketEntry.execution}, a
+ * separate question with a separate answer.
+ */
+export function isTerminal(status) {
+    return status !== "pending";
+}
+/** Every {@link RequirementKind}, in the rulebook's order. */
+export const REQUIREMENT_KINDS = [
+    "StandingOrder",
+    "ReviewerConfirmation",
+    "ReferralRequired",
+    "MultiParty",
+];
+/** Every {@link BlockedCode}. */
+export const BLOCKED_CODES = [
+    "requirement-not-implemented",
+    "coverage-refused",
+];
+/** Rejects an identifier that is empty or blank, which no store can key by. */
+function requireIdentifier(value, what) {
+    if (value.trim() === "")
+        throw new RangeError(`${what} must be a non-empty string`);
+    return value;
+}
+/**
+ * A new Docket entry, with the defaults DK-1 fixes and the correlations it requires
+ * checked.
+ *
+ * Refusals are `RangeError`, not `AffiantError`: the {@link ErrorCode} registry
+ * names the reasons *the gate refuses a request*, and a caller who hands this
+ * factory a status and an execution outcome that contradict each other has made a
+ * programming error, not a request. Keeping the two apart is what stops a host from
+ * catching a wiring bug as though it were a reviewer's rejection.
+ *
+ * @throws RangeError when an identifier is blank, an instant is unreadable, the
+ *         requirement is not one of the four, or `execution` contradicts `status`.
+ */
+export function newEntry(init) {
+    const status = init.status ?? "pending";
+    if (!DOCKET_STATUSES.includes(status)) {
+        throw new RangeError(`unknown docket status: ${String(status)}`);
+    }
+    if (!REQUIREMENT_KINDS.includes(init.requirement)) {
+        throw new RangeError(`unknown requirement kind: ${String(init.requirement)}`);
+    }
+    const execution = init.execution === undefined ? defaultExecution(status) : init.execution;
+    if (status === "approved" && execution === null) {
+        throw new RangeError("an approved entry carries an execution outcome (DK-1)");
+    }
+    if (status !== "approved" && execution !== null) {
+        throw new RangeError(`a ${status} entry carries no execution outcome (DK-1)`);
+    }
+    const filedAt = requireInstant(init.filedAt, "filedAt");
+    const expiresAt = requireInstant(init.expiresAt, "expiresAt");
+    const decidedAt = init.decidedAt === undefined ? (status === "pending" ? null : filedAt) : init.decidedAt;
+    if (status === "pending" && decidedAt !== null) {
+        throw new RangeError("a pending entry has no decidedAt (DK-1)");
+    }
+    if (status !== "pending" && decidedAt === null) {
+        throw new RangeError(`a ${status} entry records when it left pending (DK-1)`);
+    }
+    return {
+        entryId: requireIdentifier(init.entryId, "entryId"),
+        tenantId: requireIdentifier(init.tenantId, "tenantId"),
+        conversationId: requireIdentifier(init.conversationId, "conversationId"),
+        channel: requireIdentifier(init.channel, "channel"),
+        toolName: requireIdentifier(init.toolName, "toolName"),
+        affidavit: init.affidavit,
+        // A filing records what was proposed and nothing else: an amendment is a later
+        // fact, appended by a decision, never present at birth (DK-4).
+        amendedAffidavit: null,
+        requirement: init.requirement,
+        status,
+        execution,
+        blocked: init.blocked ?? null,
+        compositeRef: init.compositeRef ?? null,
+        attestation: init.attestation ?? null,
+        amendments: null,
+        preservedAmendments: null,
+        decision: null,
+        lineage: { supersedes: init.supersedes ?? null, supersededBy: null },
+        filedAt,
+        expiresAt,
+        decidedAt: decidedAt === null ? null : requireInstant(decidedAt, "decidedAt"),
+        executionDetail: null,
+        protocolVersion: init.protocolVersion ?? PROTOCOL_VERSION,
+    };
+}
+/** The execution outcome a freshly filed entry in `status` carries. */
+function defaultExecution(status) {
+    return status === "approved" ? "unexecuted" : null;
+}
+// ---------------------------------------------------------------------------
+// Expiry as state (DK-1)
+// ---------------------------------------------------------------------------
+/**
+ * What `entry` reads as at `now` — the status every query path reports.
+ *
+ * A `pending` entry past its `expiresAt` reads `expired` **whether or not any sweep
+ * has run**. That is the whole of DK-1's expiry clause, and it is a pure function of
+ * the row and the instant precisely so that no code path can forget it: there is no
+ * background job to be down, no alarm to be dropped, and no window in which an entry
+ * is decidable because nobody swept it yet.
+ *
+ * Any other status is returned unchanged. Expiry only ever consumes `pending`; a row
+ * that was approved before its deadline stays approved forever after it.
+ *
+ * @throws RangeError when `now` or the entry's `expiresAt` is not a readable instant.
+ */
+export function readStatus(entry, now) {
+    return entry.status === "pending" && isDue(entry, now) ? "expired" : entry.status;
+}
+//# sourceMappingURL=entry.js.map

package/dist/docket/entry.js.map

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

package/dist/docket/expiry.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Expiry, as state rather than as an event.
+ *
+ * **Rules served: DK-1** (an entry past `expiresAt` reads `expired` on query
+ * whether or not any sweep has run), **DK-3** (the sweep is bounded, paged and
+ * host-scheduled; the core owns no timer).
+ *
+ * There is no `setTimeout` and no `setInterval` in this package, and a test greps
+ * `src/` to keep it that way. That is not tidiness — it is the rule. The shipped
+ * .NET implementation runs an unbounded 30-second sweep over every pending entry on
+ * every instance; a core that schedules its own work cannot run on a serverless
+ * isolate at all (RT-2), and a deadline that only takes effect when a background job
+ * happens to be up is a deadline a host can silently lose. So the deadline is a
+ * *predicate over the row*, applied on every read, and the host's sweep
+ * ({@link DocketStore.expireDue}) exists to make that state durable and to drive
+ * notifications — not to make it true.
+ *
+ * Every function here is pure and synchronous. They take the instant as a parameter
+ * rather than reading a clock, so a fixture can pin a deadline to the millisecond.
+ *
+ * @packageDocumentation
+ */
+import type { DocketEntry } from "./entry.js";
+/**
+ * `instant` unchanged, once it is known to be readable.
+ *
+ * An unreadable instant throws rather than comparing as `NaN`. A `NaN` comparison
+ * is `false` in both directions, so an entry with an unparseable `expiresAt` would
+ * be *permanently decidable* — the deadline would silently stop existing, which is
+ * the one failure mode this module is here to prevent. A row can only acquire an
+ * unreadable deadline if a caller built it by hand, and {@link newEntry} refuses to
+ * do that.
+ *
+ * @throws RangeError when `instant` is not a date string any runtime can read.
+ */
+export declare function requireInstant(instant: string, what: string): string;
+/**
+ * `instant` as milliseconds since the epoch.
+ *
+ * @throws RangeError when `instant` is not a date string any runtime can read.
+ */
+export declare function instantMs(instant: string, what?: string): number;
+/** As much of an entry as the expiry predicates read. */
+export type Expirable = Pick<DocketEntry, "status" | "expiresAt">;
+/**
+ * Whether `entry` has passed its deadline at `now` — the predicate
+ * {@link readStatus} and the sweep both apply.
+ *
+ * Only a `pending` entry can be due. A row that was approved or rejected before its
+ * deadline stays that way forever after it, and a row already marked `expired` is
+ * not due *again* — `expireDue` must not keep finding the same entries.
+ *
+ * The deadline is inclusive of the instant itself: an entry whose `expiresAt` is
+ * exactly `now` is due. Half-open the other way would leave a one-millisecond window
+ * in which the row is decidable at its own deadline, and a fixture that pins the two
+ * to the same instant would then assert the wrong thing.
+ *
+ * @throws RangeError when `now` or `entry.expiresAt` is not a readable instant.
+ */
+export declare function isDue(entry: Expirable, now: string): boolean;
+/**
+ * How long `entry` has left at `now`, in milliseconds.
+ *
+ * `0` for an entry that is due or is no longer `pending` — never a negative number.
+ * A caller asking "how long is left" is deciding whether to show a countdown or to
+ * stop offering the card, and a negative answer only invites a sign bug at the call
+ * site.
+ *
+ * @throws RangeError when `now` or `entry.expiresAt` is not a readable instant.
+ */
+export declare function remainingMs(entry: Expirable, now: string): number;
+/**
+ * Whether `a` was filed before `b` — the total order every list, every sweep, every
+ * export and the rehydration sequence (DK-5) reads in.
+ *
+ * `filedAt` alone is not a total order: two entries filed in the same millisecond
+ * tie, and a store that let ties fall out in hash order would rehydrate a session
+ * differently on each reconnect. The entry id breaks the tie, by code point, so the
+ * order is the same everywhere and on every runtime.
+ */
+export declare function compareFilingOrder(a: Pick<DocketEntry, "filedAt" | "entryId">, b: Pick<DocketEntry, "filedAt" | "entryId">): number;
+//# sourceMappingURL=expiry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"expiry.d.ts","sourceRoot":"","sources":["../../src/docket/expiry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKpE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,SAAY,GAAG,MAAM,CAMnE;AAED,yDAAyD;AACzD,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,QAAQ,GAAG,WAAW,CAAC,CAAC;AAElE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAG5D;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAIjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,SAAS,GAAG,SAAS,CAAC,EAC3C,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,SAAS,GAAG,SAAS,CAAC,GAC1C,MAAM,CAKR"}

package/dist/docket/expiry.js

@@ -0,0 +1,106 @@
+/**
+ * Expiry, as state rather than as an event.
+ *
+ * **Rules served: DK-1** (an entry past `expiresAt` reads `expired` on query
+ * whether or not any sweep has run), **DK-3** (the sweep is bounded, paged and
+ * host-scheduled; the core owns no timer).
+ *
+ * There is no `setTimeout` and no `setInterval` in this package, and a test greps
+ * `src/` to keep it that way. That is not tidiness — it is the rule. The shipped
+ * .NET implementation runs an unbounded 30-second sweep over every pending entry on
+ * every instance; a core that schedules its own work cannot run on a serverless
+ * isolate at all (RT-2), and a deadline that only takes effect when a background job
+ * happens to be up is a deadline a host can silently lose. So the deadline is a
+ * *predicate over the row*, applied on every read, and the host's sweep
+ * ({@link DocketStore.expireDue}) exists to make that state durable and to drive
+ * notifications — not to make it true.
+ *
+ * Every function here is pure and synchronous. They take the instant as a parameter
+ * rather than reading a clock, so a fixture can pin a deadline to the millisecond.
+ *
+ * @packageDocumentation
+ */
+/**
+ * `instant` unchanged, once it is known to be readable.
+ *
+ * An unreadable instant throws rather than comparing as `NaN`. A `NaN` comparison
+ * is `false` in both directions, so an entry with an unparseable `expiresAt` would
+ * be *permanently decidable* — the deadline would silently stop existing, which is
+ * the one failure mode this module is here to prevent. A row can only acquire an
+ * unreadable deadline if a caller built it by hand, and {@link newEntry} refuses to
+ * do that.
+ *
+ * @throws RangeError when `instant` is not a date string any runtime can read.
+ */
+export function requireInstant(instant, what) {
+    if (Number.isNaN(Date.parse(instant))) {
+        throw new RangeError(`${what} must be a readable ISO 8601 instant, got: ${instant}`);
+    }
+    return instant;
+}
+/**
+ * `instant` as milliseconds since the epoch.
+ *
+ * @throws RangeError when `instant` is not a date string any runtime can read.
+ */
+export function instantMs(instant, what = "instant") {
+    const ms = Date.parse(instant);
+    if (Number.isNaN(ms)) {
+        throw new RangeError(`${what} must be a readable ISO 8601 instant, got: ${instant}`);
+    }
+    return ms;
+}
+/**
+ * Whether `entry` has passed its deadline at `now` — the predicate
+ * {@link readStatus} and the sweep both apply.
+ *
+ * Only a `pending` entry can be due. A row that was approved or rejected before its
+ * deadline stays that way forever after it, and a row already marked `expired` is
+ * not due *again* — `expireDue` must not keep finding the same entries.
+ *
+ * The deadline is inclusive of the instant itself: an entry whose `expiresAt` is
+ * exactly `now` is due. Half-open the other way would leave a one-millisecond window
+ * in which the row is decidable at its own deadline, and a fixture that pins the two
+ * to the same instant would then assert the wrong thing.
+ *
+ * @throws RangeError when `now` or `entry.expiresAt` is not a readable instant.
+ */
+export function isDue(entry, now) {
+    if (entry.status !== "pending")
+        return false;
+    return instantMs(entry.expiresAt, "expiresAt") <= instantMs(now, "now");
+}
+/**
+ * How long `entry` has left at `now`, in milliseconds.
+ *
+ * `0` for an entry that is due or is no longer `pending` — never a negative number.
+ * A caller asking "how long is left" is deciding whether to show a countdown or to
+ * stop offering the card, and a negative answer only invites a sign bug at the call
+ * site.
+ *
+ * @throws RangeError when `now` or `entry.expiresAt` is not a readable instant.
+ */
+export function remainingMs(entry, now) {
+    if (entry.status !== "pending")
+        return 0;
+    const left = instantMs(entry.expiresAt, "expiresAt") - instantMs(now, "now");
+    return left > 0 ? left : 0;
+}
+/**
+ * Whether `a` was filed before `b` — the total order every list, every sweep, every
+ * export and the rehydration sequence (DK-5) reads in.
+ *
+ * `filedAt` alone is not a total order: two entries filed in the same millisecond
+ * tie, and a store that let ties fall out in hash order would rehydrate a session
+ * differently on each reconnect. The entry id breaks the tie, by code point, so the
+ * order is the same everywhere and on every runtime.
+ */
+export function compareFilingOrder(a, b) {
+    const byInstant = instantMs(a.filedAt, "filedAt") - instantMs(b.filedAt, "filedAt");
+    if (byInstant !== 0)
+        return byInstant;
+    if (a.entryId === b.entryId)
+        return 0;
+    return a.entryId < b.entryId ? -1 : 1;
+}
+//# sourceMappingURL=expiry.js.map

package/dist/docket/expiry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expiry.js","sourceRoot":"","sources":["../../src/docket/expiry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe,EAAE,IAAY;IAC1D,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,8CAA8C,OAAO,EAAE,CAAC,CAAC;IACvF,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe,EAAE,IAAI,GAAG,SAAS;IACzD,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC/B,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,8CAA8C,OAAO,EAAE,CAAC,CAAC;IACvF,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAKD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,KAAK,CAAC,KAAgB,EAAE,GAAW;IACjD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAC7C,OAAO,SAAS,CAAC,KAAK,CAAC,SAAS,EAAE,WAAW,CAAC,IAAI,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;AAC1E,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,KAAgB,EAAE,GAAW;IACvD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,SAAS,EAAE,WAAW,CAAC,GAAG,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC7E,OAAO,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAChC,CAA2C,EAC3C,CAA2C;IAE3C,MAAM,SAAS,GAAG,SAAS,CAAC,CAAC,CAAC,OAAO,EAAE,SAAS,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACpF,IAAI,SAAS,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACtC,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO;QAAE,OAAO,CAAC,CAAC;IACtC,OAAO,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACxC,CAAC"}

package/dist/docket/memory.d.ts

@@ -0,0 +1,163 @@
+/**
+ * The reference Docket and Session stores, in memory.
+ *
+ * **Rules served: DK-1** (idempotent filing, the guarded compare-and-set, expiry as
+ * queryable state, preserved amendments on a late decision, execution outcome,
+ * lineage), **DK-3** (a bounded, paged sweep and no timer), **DK-4** (retention,
+ * purge, export, read-forward), **DK-5** (rehydration order), **AZ-2** (tenant
+ * isolation), **RT-2** (nothing unbounded but a purge).
+ *
+ * "In memory" is not "toy". This is the *reference* store: it is what the
+ * store-semantics fixtures are written against, and a Postgres store earns the name
+ * by passing the same ones. Everything a production store has to get right is here
+ * — the compare-and-set, the deadline applied on read, the opaque paging, the
+ * tenant partition — because a reference that skipped them would let a fixture pass
+ * for the wrong reason.
+ *
+ * **How the compare-and-set is atomic without a lock.** JavaScript is
+ * single-threaded, but `await` is an interleaving point: any method that reads state,
+ * awaits, and then writes it has a window in which another caller can run. So every
+ * mutating method here does its read and its write in **one synchronous block** —
+ * the `async` wrapper contains no `await` at all, which means the body runs to
+ * completion before the caller's next turn of the event loop. Two `transition` calls
+ * launched together with `Promise.all` therefore serialize, and exactly one wins the
+ * guard. A production store gets the same property from a conditional `UPDATE`; the
+ * shape of the fixture is identical either way.
+ *
+ * **Storage layout.** One `Map` per tenant, keyed by entry id, so a cross-tenant read
+ * is not a filtered read but an impossible one — there is no code path that looks in
+ * another tenant's map. `Map` preserves insertion order, which *is* filing order, so
+ * every list, sweep and export walks it directly rather than sorting. A sequence
+ * number per row makes that position addressable by an opaque cursor.
+ *
+ * @packageDocumentation
+ */
+import type { AmendmentMap } from "../model/amendments.js";
+import type { Clock } from "../ports.js";
+import type { DocketEntry, ExecutionOutcome } from "./entry.js";
+import type { DocketStore, Page, PageResult, PreservedAct, PreserveAmendmentsResult, RecordExecutionResult, RecordSupersessionResult, RetentionPolicy, Scope, SessionStore, TransitionPatch, TransitionResult } from "./store.js";
+/** How the in-memory Docket store is built. */
+export interface InMemoryDocketStoreOptions {
+    /**
+     * Where "now" comes from, for the deadline every read applies (DK-1).
+     *
+     * A store needs a clock rather than a `now` parameter on each method because the
+     * deadline is the store's answer to give: a method that let the caller supply the
+     * instant would let the caller decide whether an entry had expired. A fixture
+     * pins the instant by passing a stub clock here. Defaults to
+     * {@link defaultClock}.
+     */
+    readonly clock?: Clock;
+}
+/**
+ * The reference Docket store: one `Map` per tenant, every rule in the DK area
+ * enforced, no timer anywhere.
+ */
+export declare class InMemoryDocketStore implements DocketStore {
+    #private;
+    constructor(options?: InMemoryDocketStoreOptions);
+    /**
+     * File `entry`, or return the one already filed under its id — never an error,
+     * never an overwrite, never a refreshed deadline (DK-1, GT-4).
+     */
+    file(entry: DocketEntry): Promise<{
+        entry: DocketEntry;
+        created: boolean;
+    }>;
+    /** The entry as it reads now, or `null` when nothing in `scope` has that id. */
+    get(entryId: string, scope: Scope): Promise<DocketEntry | null>;
+    /**
+     * The guarded compare-and-set (DK-1).
+     *
+     * No `await` between the read of the current state and the write of the new one:
+     * that is what makes it atomic against every other caller in this isolate.
+     */
+    transition(entryId: string, scope: Scope, expected: "pending", patch: TransitionPatch): Promise<TransitionResult>;
+    /**
+     * Preserve the amendments a late decision carried, for a resubmission (DK-1).
+     *
+     * Writes `preservedAmendments` and nothing else: not `status`, not `decision`, not
+     * `attestation`. The row's stored status stays as it was — it already *reads*
+     * `expired`, and recording a sweep the host did not run would be this method
+     * quietly doing a second job.
+     */
+    preserveAmendments(entryId: string, scope: Scope, amendments: AmendmentMap, act: PreservedAct): Promise<PreserveAmendmentsResult>;
+    /**
+     * Record what the host's executor reported on an approved row, once (DK-1, DK-4).
+     *
+     * A guarded compare-and-set on the row's own `execution`, read and written in the
+     * same synchronous block as every other mutation here, so two reports racing
+     * serialize and exactly one wins. The second is refused rather than applied on
+     * top: an outcome is a recorded fact, and a row reads forward.
+     */
+    recordExecution(entryId: string, scope: Scope, outcome: Exclude<ExecutionOutcome, "unexecuted">, detail: string | null, expected: "unexecuted"): Promise<RecordExecutionResult>;
+    /** Record the successor of a terminal row (DK-1); the row keeps its terminal state. */
+    recordSupersession(entryId: string, scope: Scope, supersededBy: string): Promise<RecordSupersessionResult>;
+    /** Everything that reads `pending` right now, in filing order, paged. */
+    listPending(scope: Scope, page: Page): Promise<PageResult<DocketEntry>>;
+    /** Everything approved and still unexecuted, in filing order, paged. */
+    listApprovedUnexecuted(scope: Scope, page: Page): Promise<PageResult<DocketEntry>>;
+    /**
+     * Mark at most `limit` due entries `expired`, in filing order, and say whether more
+     * remain (DK-3).
+     *
+     * `decidedAt` is set to the entry's own `expiresAt`, not to `now`: the row left
+     * `pending` at its deadline, which is when a reader who never ran a sweep would
+     * have seen it go. A swept row and an unswept one past the same deadline are then
+     * the same value, so a host cannot tell — and cannot come to depend on — whether
+     * the sweep has caught up.
+     */
+    expireDue(now: string, scope: Scope, limit: number): Promise<{
+        expired: string[];
+        more: boolean;
+    }>;
+    /**
+     * Remove at most `limit` terminal entries whose terminal instant is before
+     * `policy.olderThan` (DK-4).
+     *
+     * An `approved` row that is still `unexecuted` is **never** eligible, however old.
+     * It is the only record that a write was authorised and has not yet happened, and
+     * the Docket is the sole record of approval authority (AZ-5) — ageing it out would
+     * delete the evidence and the outstanding work in one move.
+     */
+    retention(policy: RetentionPolicy, scope: Scope, limit: number): Promise<{
+        removed: number;
+        more: boolean;
+    }>;
+    /** Remove everything belonging to `tenantId`, and nothing else (DK-4). */
+    purge(tenantId: string): Promise<{
+        removed: number;
+    }>;
+    /**
+     * Every entry in `scope`, in filing order, streamed (DK-4).
+     *
+     * The ids are snapshotted when iteration begins and each row is read as the
+     * consumer reaches it, so a concurrent transition is reflected and a concurrent
+     * retention pass cannot make the iterator yield a row that has been removed.
+     */
+    export(scope: Scope): AsyncIterable<DocketEntry>;
+}
+/**
+ * The reference Session store: rehydration in the order DK-5 fixes.
+ *
+ * It is built **on** a {@link DocketStore} rather than beside one, and it uses only
+ * the public interface. That is deliberate: DK-5's order has to hold for any store a
+ * host plugs in, so the reference implementation proves the `DocketStore` contract
+ * is sufficient to produce it. A session store that reached into the in-memory
+ * store's internals would prove nothing.
+ */
+export declare class InMemorySessionStore implements SessionStore {
+    #private;
+    constructor(docket: DocketStore);
+    /**
+     * One page of: everything that reads `pending`, then everything `approved` and
+     * `unexecuted`, each in filing order (DK-5).
+     *
+     * A page boundary that falls inside the first group resumes there; one that drains
+     * it resumes at the start of the second. A reconnecting client therefore sees what
+     * still needs a decision before what still needs execution, however small its page
+     * size.
+     */
+    rehydrate(scope: Scope, page: Page): Promise<PageResult<DocketEntry>>;
+}
+//# sourceMappingURL=memory.d.ts.map

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

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