@affiant/core 0.1.0-alpha.0

package/dist/context.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Turn context — the object every gate entry point takes as a parameter.
+ *
+ * **Rules served: GT-2** (the conversation-scope contract), **AZ-3** (a relay may
+ * never attest as the person it speaks for).
+ *
+ * GT-2 in one sentence: *turn context is explicit and passed, never ambient.*
+ * Every entry point on the gate takes a {@link TurnContext} — conversation id,
+ * tenant, channel, the principal if one is resolved, and the unmodified turn —
+ * supplied by the host or the adapter at the call site. Nothing in this package
+ * reads a process-global, a thread-ambient store or a container default; there is
+ * no module-level mutable state here for two interleaved conversations to collide
+ * in, and no accessor a caller could reach for instead of passing the context. An
+ * adapter that cannot obtain a context at its seam refuses (CV-2) rather than
+ * falling back to a shared default.
+ *
+ * Why the rule exists: in the shipped .NET wiring the tool-invocation seam resolves
+ * its scoped context store from the application's root provider, so one
+ * process-global instance is shared by every conversation — field provenance is
+ * overwritten across conversations, and where the host supplies no conversation id
+ * the second and later conversations skip write-tool inference silently.
+ *
+ * Every property below is `readonly`. A context is a value the host hands in, not a
+ * scratchpad the gate writes back to; freezing the shape in the type is how "never
+ * ambient" stays true after the pipeline lands.
+ *
+ * @packageDocumentation
+ */
+/**
+ * How a person is addressed on the channel a relay speaks for — a workspace member
+ * id, a phone number, an address, whatever the relay's own directory uses. Opaque
+ * to the gate: it is carried onto the record and compared for equality, never
+ * parsed.
+ *
+ * It is a `string` on the wire and in every signature; the alias exists so the
+ * concept has one name across the packages.
+ */
+export type ChannelIdentity = string;
+/**
+ * What a relay asserts about the message it is carrying: which identity on its
+ * channel the message came from, and the id of the message itself.
+ *
+ * A relay is a trusted machine caller that *asserts* a person's identity rather
+ * than authenticating them. Both fields are carried onto the Affidavit's
+ * `external-ref` binding and onto the attestation of any decision made through the
+ * relay, so a reader of the record can name the message a write came from.
+ */
+export interface RelayAssertion {
+    /** The identity, on the relay's own channel, the message came from. */
+    readonly channelIdentity: ChannelIdentity;
+    /** The relay's id for the message that carried the request. */
+    readonly messageId: string;
+}
+/**
+ * Who is acting on this turn.
+ *
+ * `member` is a human-verified session: the host authenticated the person itself.
+ * `service` is a machine caller — an MCP relay, a queue consumer, a scheduled job.
+ * A `service` principal may name the person it is speaking for
+ * ({@link Principal.assertedMember}) and the message it is carrying
+ * ({@link Principal.relay}), but **AZ-3** holds regardless: a `service` principal
+ * can never produce a `member` attestation. The strongest attestation a relayed
+ * decision can carry is `member-via-relay`, which names both the person and the
+ * relay.
+ *
+ * `null` in {@link TurnContext.principal} means *unresolved*, which is not the same
+ * as anonymous: a decision on an unresolved principal is refused
+ * (`decision-unauthorized`) before the store is touched (AZ-2).
+ */
+export type Principal = {
+    /** A human-verified session. */
+    readonly kind: "member";
+    /** The host's id for the person. */
+    readonly id: string;
+} | {
+    /** A machine caller: a relay, a queue consumer, a scheduled job. */
+    readonly kind: "service";
+    /** The host's id for the calling service. */
+    readonly id: string;
+    /**
+     * The message this service is carrying, when it is a relay. Absent when the
+     * service is acting on its own behalf.
+     */
+    readonly relay?: RelayAssertion;
+    /**
+     * The person this service says it is speaking for. An assertion, not an
+     * authentication — it never upgrades the principal to `member` (AZ-3).
+     */
+    readonly assertedMember?: string;
+};
+/**
+ * The turn as the host received it, unmodified.
+ *
+ * The gate hands exactly this to the host's inference port: one tool-free
+ * structured inference runs against the untouched utterance, so what the Affidavit
+ * swears to is traceable to what the person actually wrote.
+ *
+ * Structurally identical to `TurnContext["turn"]`; the alias exists so ports can
+ * name it.
+ */
+export interface Turn {
+    /** What the person wrote or said, verbatim. */
+    readonly utterance: string;
+    /** The host's id for this message. */
+    readonly messageId: string;
+    /** When the turn arrived, as an ISO 8601 instant in UTC. */
+    readonly at: string;
+}
+/**
+ * Everything the gate is allowed to know about who is asking and where they are
+ * asking from — passed at the call site, never resolved from ambient state (GT-2).
+ *
+ * Two contexts constructed in the same process describe two different
+ * conversations and share nothing: there is no registry keyed by conversation id
+ * in this package, and no default context to fall back to.
+ */
+export interface TurnContext {
+    /** The host's id for the conversation this turn belongs to. */
+    readonly conversationId: string;
+    /**
+     * The tenant every record written for this turn is scoped to. A decision whose
+     * context tenant differs from the entry's tenant is refused (AZ-2).
+     */
+    readonly tenantId: string;
+    /**
+     * Where the turn arrived from. The three named values are the ones the v0.1
+     * sequences use; the `(string & {})` arm keeps the union open to a host's own
+     * channel name without losing completion on the three.
+     */
+    readonly channel: "chat" | "mcp" | "api" | (string & {});
+    /** Who is acting, or `null` when the host has not resolved an identity. */
+    readonly principal: Principal | null;
+    /** The turn itself, unmodified. */
+    readonly turn: Turn;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC;AAErC;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,SAAS,GACjB;IACE,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,oCAAoC;IACpC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB,GACD;IACE,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC,CAAC;AAEN;;;;;;;;;GASG;AACH,MAAM,WAAW,IAAI;IACnB,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sCAAsC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACzD,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IACrC,mCAAmC;IACnC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;CACrB"}

package/dist/context.js

@@ -0,0 +1,30 @@
+/**
+ * Turn context — the object every gate entry point takes as a parameter.
+ *
+ * **Rules served: GT-2** (the conversation-scope contract), **AZ-3** (a relay may
+ * never attest as the person it speaks for).
+ *
+ * GT-2 in one sentence: *turn context is explicit and passed, never ambient.*
+ * Every entry point on the gate takes a {@link TurnContext} — conversation id,
+ * tenant, channel, the principal if one is resolved, and the unmodified turn —
+ * supplied by the host or the adapter at the call site. Nothing in this package
+ * reads a process-global, a thread-ambient store or a container default; there is
+ * no module-level mutable state here for two interleaved conversations to collide
+ * in, and no accessor a caller could reach for instead of passing the context. An
+ * adapter that cannot obtain a context at its seam refuses (CV-2) rather than
+ * falling back to a shared default.
+ *
+ * Why the rule exists: in the shipped .NET wiring the tool-invocation seam resolves
+ * its scoped context store from the application's root provider, so one
+ * process-global instance is shared by every conversation — field provenance is
+ * overwritten across conversations, and where the host supplies no conversation id
+ * the second and later conversations skip write-tool inference silently.
+ *
+ * Every property below is `readonly`. A context is a value the host hands in, not a
+ * scratchpad the gate writes back to; freezing the shape in the type is how "never
+ * ambient" stays true after the pipeline lands.
+ *
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

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

package/dist/docket/entry.d.ts

@@ -0,0 +1,421 @@
+/**
+ * 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 type { Affidavit } from "../model/affidavit.js";
+import type { AmendmentMap } from "../model/amendments.js";
+import type { ChannelIdentity, TurnContext } from "../context.js";
+/**
+ * Where an entry stands. `pending` is the only non-terminal state, and it goes to
+ * exactly one of the other three (DK-1).
+ *
+ * `deferred` and the referral outcome — an entry handed to another reviewer — are
+ * **reserved** by the rulebook and deliberately absent: no implementation has run
+ * those transitions, so naming them here would invite a host to depend on
+ * semantics nobody has fixed.
+ */
+export type DocketStatus = "pending" | "approved" | "rejected" | "expired";
+/** Every {@link DocketStatus}, pinned as data so a runtime check and a fixture read the same list. */
+export declare const DOCKET_STATUSES: readonly ["pending", "approved", "rejected", "expired"];
+/**
+ * What became of an approved write, once the host's executor reported.
+ *
+ * The reason this is a separate axis rather than two more statuses: an
+ * approved-but-failed write and an approved-and-committed one differ in what the
+ * *host* must do next, not in whether the approval happened. Collapsing them into
+ * `status` loses the approval, and DK-1 requires the two be distinguishable on the
+ * row.
+ */
+export type ExecutionOutcome = "unexecuted" | "executed" | "failed";
+/** Every {@link ExecutionOutcome}, in the order a row moves through them. */
+export declare const EXECUTION_OUTCOMES: readonly ["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 declare function isTerminal(status: DocketStatus): boolean;
+/**
+ * How much agreement a write needs before it may execute — the policy chain's
+ * verdict kind, recorded verbatim on the entry.
+ *
+ * `StandingOrder` approves with no person present. `ReviewerConfirmation` asks one
+ * person. `ReferralRequired` hands the entry to a different reviewer, and
+ * `MultiParty` requires several — **neither of which v0.1 runs**. AZ-4 is emphatic
+ * about what an implementation does with a level it does not run: it records the
+ * level verbatim, files the entry `pending` with a {@link BlockedMarker}, refuses
+ * every decision on it, and **never degrades it to a weaker requirement**. A joint
+ * requirement quietly satisfied by one approval is the failure this rule exists to
+ * prevent.
+ */
+export type RequirementKind = "StandingOrder" | "ReviewerConfirmation" | "ReferralRequired" | "MultiParty";
+/** Every {@link RequirementKind}, in the rulebook's order. */
+export declare const REQUIREMENT_KINDS: readonly ["StandingOrder", "ReviewerConfirmation", "ReferralRequired", "MultiParty"];
+/**
+ * Why an entry cannot be decided even though it sits in `pending`.
+ *
+ * Both codes are **provisional** until the protocol's `ErrorCode` registry is
+ * authored with the v0.1 schemas; they match {@link ErrorCode} member for member so
+ * that a refusal thrown by the gate and the marker left on the row spell the same
+ * reason.
+ */
+export type BlockedCode = "requirement-not-implemented" | "coverage-refused";
+/** Every {@link BlockedCode}. */
+export declare const BLOCKED_CODES: readonly ["requirement-not-implemented", "coverage-refused"];
+/**
+ * A requirement level this version recognises but does not run reached the
+ * pipeline — `ReferralRequired` or `MultiParty`, whose semantics are reserved. The
+ * level is recorded verbatim and never degraded to a weaker one (AZ-4).
+ */
+export interface RequirementNotImplementedMarker {
+    readonly code: "requirement-not-implemented";
+    /** The requirement level that is not implemented. */
+    readonly level: RequirementKind;
+}
+/**
+ * A proposal came from a write-capable tool the host declared the gate cannot
+ * intercept (CV-4). Its proposals are still recorded — blocked, never silently
+ * allowed to write — and the tool name is on the row so coverage can be
+ * re-assessed on a resubmission.
+ */
+export interface CoverageRefusedMarker {
+    readonly code: "coverage-refused";
+    /** The category the gate cannot cover. */
+    readonly category: "no-execute" | "provider-executed" | "hosted-mcp";
+    /** The tool the uncovered proposal came from. */
+    readonly toolName: string;
+}
+/**
+ * The marker AZ-4 requires on an entry the implementation will not decide.
+ *
+ * Discriminated on its `code`, and each arm carries exactly the context that code
+ * makes meaningful — a `coverage-refused` marker has no requirement level to
+ * report, and a reader narrows on the code rather than sniffing for a property
+ * (AF-5).
+ */
+export type BlockedMarker = RequirementNotImplementedMarker | CoverageRefusedMarker;
+/** What a relay asserted, as it is written onto an attestation. */
+export interface AttestationRelay {
+    /** The host's id for the relay service that carried the decision. */
+    readonly principal: string;
+    /** The identity, on the relay's own channel, the decision came from. */
+    readonly channelIdentity: ChannelIdentity;
+    /** The relay's id for the message that carried the decision. */
+    readonly messageId: string;
+}
+/**
+ * Who agreed to the write. The *mode* is the `kind`; there is no separate mode
+ * field for it to drift from (AZ-1).
+ *
+ * AZ-3 is what the three arms encode. A human-verified session attests `member`. A
+ * machine caller may **never** attest `member`: a decision a person makes through a
+ * relay attests `member-via-relay`, naming both the person and the relay, and a
+ * capture a policy auto-approves attests `standing-order`, naming the policy and
+ * the version of it that fired. Making the strongest available claim explicit in
+ * the type is how an implementation avoids the shortcut where a relay's assertion
+ * is quietly promoted to a person's signature.
+ */
+export type Attestor = {
+    /** A human-verified session decided this entry. */
+    readonly kind: "member";
+    /** The host's id for the person. */
+    readonly id: string;
+} | {
+    /** A person decided this entry through a trusted relay. */
+    readonly kind: "member-via-relay";
+    /** The host's id for the person the relay named. */
+    readonly memberId: string;
+    /** The relay, and the message the decision arrived on. */
+    readonly relay: AttestationRelay;
+} | {
+    /** A policy approved this entry with no person present. */
+    readonly kind: "standing-order";
+    /** The host's id for the policy that fired. */
+    readonly policyId: string;
+    /** The version of that policy, so a later reader can tell what it said at the time. */
+    readonly version: string;
+};
+/**
+ * The attestation record AZ-1 requires on every write that reaches an executor: who
+ * agreed, when, and to which entry.
+ *
+ * `entryId` is repeated here rather than left implicit because the attestation is
+ * the fragment a host exports, signs or ships to an audit sink; a record that
+ * cannot name its own subject is not evidence.
+ */
+export interface Attestation {
+    /** Who agreed. */
+    readonly by: Attestor;
+    /** When, as an ISO 8601 instant in UTC. */
+    readonly at: string;
+    /** The entry this attests to. */
+    readonly entryId: string;
+}
+/**
+ * What a reviewer decided, as it is recorded on the row.
+ *
+ * Separate from {@link Attestation} because they answer different questions: the
+ * attestation says *who may be held to this*, the decision says *what they chose
+ * and why*. A Standing Order produces an attestation and no decision record — no
+ * person chose anything.
+ */
+export interface DecisionRecord {
+    /** Approve or reject. Amending is approving with an {@link DocketEntry.amendments} map. */
+    readonly kind: "approve" | "reject";
+    /** The reviewer's stated reason, or `null` when they gave none. */
+    readonly reason: string | null;
+    /** When the decision was made, as an ISO 8601 instant in UTC. */
+    readonly at: string;
+}
+/**
+ * How this entry relates to the entries it replaces or is replaced by (DK-1).
+ *
+ * A resubmission is a **new** entry, never a reopened one: the superseded entry
+ * keeps its terminal state and records its successor, so the history reads forward
+ * (DK-4) and nothing that was once decided is quietly edited.
+ */
+export interface Lineage {
+    /** The entry this one resubmits, or `null` for a first filing. */
+    readonly supersedes: string | null;
+    /** The entry that resubmitted this one, or `null` while none has. */
+    readonly supersededBy: string | null;
+}
+/**
+ * The amendments a decision carried after the entry had already expired, with the
+ * act that carried them (DK-1).
+ *
+ * The instant and the principal are here, and not merely implied, because a
+ * resubmission prefills these values as **a person's own correction**: each
+ * prefilled field is tagged `UserStated` with a `reviewer-act` binding, and PV-2
+ * says that binding names the decision the correction was made on. Without the
+ * instant the binding would have to point at the row's deadline — the moment the
+ * gate refused, not the moment the person typed — and without the principal the
+ * record could not say whose correction it is.
+ */
+export interface PreservedAmendments {
+    /** The map the refused decision carried. DK-2 holds inside it. */
+    readonly amendments: AmendmentMap;
+    /** When the refused decision was made, as an ISO 8601 instant in UTC. */
+    readonly at: string;
+    /** Who made it, as the host identifies them. */
+    readonly by: string;
+}
+/**
+ * One filed proposal: the Affidavit, what it needs before it may execute, where it
+ * stands, and who agreed.
+ *
+ * Every property is `readonly`. A store never mutates a row in place — a
+ * transition, a preserved amendment map, an execution outcome and a supersession
+ * each produce a *new* entry value that replaces the old one under the same id.
+ * That is DK-4's read-forward property expressed in the type rather than in a
+ * comment nobody runs.
+ *
+ * Three correlations the flat shape cannot express, enforced by {@link newEntry}
+ * and by the store's transition instead:
+ *
+ * 1. `execution` is non-`null` **exactly when** `status` is `"approved"`.
+ * 2. `decidedAt` is non-`null` on every terminal row and `null` while `pending`.
+ * 3. `status` is what the row *says*; what it *reads* is {@link readStatus}, which
+ *    applies the expiry deadline. Every query path goes through the latter.
+ */
+export interface DocketEntry {
+    /** The entry's id. Stable for its whole lifetime; a resubmission gets a new one. */
+    readonly entryId: string;
+    /**
+     * The tenant this entry is scoped to. Compared against `ctx.tenantId` before any
+     * transition (AZ-2), and the partition every store operation is keyed by: an
+     * entry id is unique within a tenant, never across them.
+     */
+    readonly tenantId: string;
+    /** The conversation the proposal came from (GT-2). */
+    readonly conversationId: string;
+    /** Where the turn arrived from — `"chat"` for Sequence A, `"mcp"` for Sequence C. */
+    readonly channel: TurnContext["channel"];
+    /**
+     * The tool or capture source the proposal came from.
+     *
+     * On the row because two later questions need it and neither can be answered
+     * from the Affidavit: a resubmission re-runs the coverage lookup against the
+     * original tool (CV-4), and an audit of a filed write has to be able to say
+     * which tool proposed it.
+     */
+    readonly toolName: string;
+    /**
+     * The sworn evidence record **as the agent proposed it**. Never edited (DK-4).
+     *
+     * An accepted amendment does not rewrite this; it writes
+     * {@link DocketEntry.amendedAffidavit} beside it. A row that overwrote its
+     * proposal could not show what the agent originally said, which is the fact an
+     * auditor is reading the row for.
+     */
+    readonly affidavit: Affidavit;
+    /**
+     * The state a reviewer's accepted amendments produced, or `null` while no
+     * amendment has been accepted (AF-4, DK-4).
+     *
+     * The form a host's execution grant binds to is
+     * `canonicalize(amendedAffidavit ?? affidavit)` — see `canonicalizeEntry` — which
+     * is what SR-1's "the Affidavit and its accepted amendments" means on a row.
+     */
+    readonly amendedAffidavit: Affidavit | null;
+    /** What the policy chain decided this write needs before it may execute (AZ-4). */
+    readonly requirement: RequirementKind;
+    /** What the row says. What it *reads* is {@link readStatus}. */
+    readonly status: DocketStatus;
+    /** What became of the write. Non-`null` exactly when `status` is `"approved"`. */
+    readonly execution: ExecutionOutcome | null;
+    /** Why this entry cannot be decided, or `null` when it can (AZ-4). */
+    readonly blocked: BlockedMarker | null;
+    /**
+     * The composite approval this entry is one constituent of, or `null`.
+     *
+     * Until `MultiParty` is protocol v0.2, a host composes multi-party approval
+     * *above* the gate: one entry per approver, all naming the same composite, and
+     * no constituent's approval alone reaching the executor (AZ-4).
+     */
+    readonly compositeRef: string | null;
+    /** Who agreed, or `null` while nobody has (AZ-1). */
+    readonly attestation: Attestation | null;
+    /**
+     * The amendments a reviewer's approval **accepted**, or `null` when the approval
+     * carried none.
+     *
+     * Within a map, DK-2 holds: a key whose value is `null` was **cleared** by the
+     * reviewer, and an absent key was left untouched. The two are never conflated.
+     *
+     * A map a *refused* late decision carried is a different fact and lives under
+     * {@link DocketEntry.preservedAmendments}: nobody accepted it, and conflating the
+     * two would let a resubmission present a refused caller's corrections as an
+     * approval's.
+     */
+    readonly amendments: AmendmentMap | null;
+    /**
+     * The amendments a decision carried after the deadline had passed, with the act
+     * that carried them, or `null` (DK-1).
+     *
+     * An appended later fact on an expired row, written by the store's
+     * `preserveAmendments` and read by `resubmit` to prefill the new proposal.
+     */
+    readonly preservedAmendments: PreservedAmendments | null;
+    /** What a reviewer chose, or `null` for a pending row or a Standing Order. */
+    readonly decision: DecisionRecord | null;
+    /** What this entry replaces and what replaced it (DK-1). */
+    readonly lineage: Lineage;
+    /** When the entry was filed, as an ISO 8601 instant in UTC. Fixes the filing order. */
+    readonly filedAt: string;
+    /**
+     * The deadline, as an ISO 8601 instant in UTC. Set from the policy verdict's TTL
+     * after the policy chain has run (GT-4), and **never refreshed by a re-file**.
+     */
+    readonly expiresAt: string;
+    /** When the row left `pending`, or `null` while it has not. */
+    readonly decidedAt: string | null;
+    /** What the executor reported, or `null` when it has not reported or had nothing to say. */
+    readonly executionDetail: string | null;
+    /** The protocol tag the entry's wire shapes are pinned to. */
+    readonly protocolVersion: string;
+}
+/**
+ * What {@link newEntry} needs, and the few defaults a caller may override.
+ *
+ * The overridable set is deliberately small: everything else on a
+ * {@link DocketEntry} is a *later fact* — a decision, a preserved amendment map, an
+ * execution outcome, a supersession — and later facts are appended by the store, not
+ * supplied at filing. The exceptions are the ones the pipeline genuinely writes in
+ * the same operation as the filing: a Standing Order verdict files `approved`,
+ * `unexecuted` and its attestation in one write (GT-1 step 9, AZ-1), and an
+ * unimplemented requirement files `pending` with a blocked marker (AZ-4).
+ */
+export interface NewEntryInit {
+    /** The entry's id. Unique within the tenant. */
+    readonly entryId: string;
+    /** The tenant the entry is scoped to. */
+    readonly tenantId: string;
+    /** The conversation the proposal came from. */
+    readonly conversationId: string;
+    /** Where the turn arrived from. */
+    readonly channel: TurnContext["channel"];
+    /** The tool or capture source the proposal came from (CV-4). */
+    readonly toolName: string;
+    /** The sworn evidence record, as proposed. */
+    readonly affidavit: Affidavit;
+    /** What the policy chain decided this write needs. */
+    readonly requirement: RequirementKind;
+    /** When the entry is being filed, as an ISO 8601 instant in UTC. */
+    readonly filedAt: string;
+    /** The deadline, as an ISO 8601 instant in UTC (GT-4). */
+    readonly expiresAt: string;
+    /** The protocol tag. Defaults to the tag `@affiant/contract` is pinned to. */
+    readonly protocolVersion?: string;
+    /** Defaults to `"pending"`. A Standing Order files `"approved"`. */
+    readonly status?: DocketStatus;
+    /**
+     * Defaults to `"unexecuted"` when `status` is `"approved"` and `null` otherwise.
+     * Supplying a value that contradicts the status is a `RangeError`.
+     */
+    readonly execution?: ExecutionOutcome | null;
+    /** The AZ-4 marker, when the entry is filed blocked. */
+    readonly blocked?: BlockedMarker | null;
+    /** The composite approval this entry is a constituent of. */
+    readonly compositeRef?: string | null;
+    /** The attestation a Standing Order writes in the same operation as the filing (AZ-1). */
+    readonly attestation?: Attestation | null;
+    /** The entry this one resubmits (DK-1). The successor link is written on the *other* row. */
+    readonly supersedes?: string | null;
+    /**
+     * When the row left `pending`, for an entry filed already terminal. Defaults to
+     * `filedAt` in that case, and is `null` for a `pending` filing.
+     */
+    readonly decidedAt?: string | null;
+}
+/**
+ * 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 declare function newEntry(init: NewEntryInit): DocketEntry;
+/**
+ * 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 declare function readStatus(entry: Pick<DocketEntry, "status" | "expiresAt">, now: string): DocketStatus;
+//# sourceMappingURL=entry.d.ts.map

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

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