@agentcomms/whatsapp 0.13.1 → 0.14.1

package/dist/index.d.mts

@@ -4277,7 +4277,25 @@ declare namespace external_d_exports {
   export { $brand, $input, $output, BRAND, CompileOptions, GlobalMeta, INVALID, Infer$1 as Infer, IssueData, JSONType, NEVER, $RefinementCtx as RefinementCtx, SafeExtendShape, Schema, TimePrecision, TypeOf, ZodAny, ZodArray, ZodBase64, ZodBase64URL, ZodBigInt, ZodBigIntFormat, ZodBoolean, ZodCIDRv4, ZodCIDRv6, ZodCUID, ZodCUID2, ZodCatch, ZodCodec, ZodCoercedBigInt, ZodCoercedBoolean, ZodCoercedDate, ZodCoercedNumber, ZodCoercedString, ZodCompileAsyncError, ZodCompileUnsupportedError, ZodCreditCard, ZodCustom, ZodCustomStringFormat, ZodDate, ZodDefault, ZodDiscriminatedUnion, ZodE164, ZodEmail, ZodEmoji, ZodEnum, ZodError, ZodErrorMap, ZodExactOptional, ZodFile, ZodFirstPartySchemaTypes, ZodFirstPartyTypeKind, ZodFlattenedError, ZodFloat32, ZodFloat64, ZodFormattedError, ZodFunction, ZodGUID, ZodIBAN, ZodIPv4, ZodIPv6, ZodISODate, ZodISODateTime, ZodISODuration, ZodISOTime, ZodInstanceOf, ZodInt, ZodInt32, ZodInt64, ZodIntersection, ZodIssue, ZodIssueCode, ZodJSONSchema, ZodJSONSchemaInternals, ZodJWT, ZodKSUID, ZodLazy, ZodLiteral, ZodMAC, ZodMap, ZodNaN, ZodNanoID, ZodNever, ZodNonOptional, ZodNull, ZodNullable, ZodNumber, ZodNumberFormat, ZodObject, ZodOptional, ZodPipe, ZodPrefault, ZodPreprocess, ZodPromise, ZodRawShape$1 as ZodRawShape, ZodReadonly, ZodRealError, ZodRecord, ZodSafeParseError, ZodSafeParseResult, ZodSafeParseSuccess, ZodSchema, ZodSet, ZodStandardSchemaWithJSON, ZodString, ZodStringFormat, ZodSuccess, ZodSymbol, ZodTemplateLiteral, ZodTransform, ZodTuple, ZodType, ZodTypeAny, ZodUInt32, ZodUInt64, ZodULID, ZodURL, ZodUUID, ZodUndefined, ZodUnion, ZodUnknown, ZodVoid, ZodXID, ZodXor, _ZodBigInt, _ZodBoolean, _ZodDate, _ZodNumber, _ZodString, _ZodType, _default, _function, any, array, base64, base64url, bigint$1 as bigint, boolean$1 as boolean, _catch as catch, check, cidrv4, cidrv6, clone, codec, coerce_d_exports as coerce, compile, config, index_d_exports$1 as core, creditCard, cuid, cuid2, currencyCode, custom, date$2 as date, decode, decodeAsync, deepPartial, describe, discriminatedUnion, e164, email, emoji, encode, encodeAsync, _endsWith as endsWith, _enum as enum, exactOptional, file, flattenError, float32, float64, formatError, fromJSONSchema, _function as function, getDiscriminatedOption, getErrorMap, globalRegistry, _gt as gt, _gte as gte, guid, hash, hex, hostname, httpUrl, iban, _includes as includes, output$1 as infer, inferFlattenedErrors, inferFormattedError, input, _instanceof as instanceof, int, int32, int64, intersection, invertCodec, ipv4, ipv6, iso_d_exports as iso, json, jwt, keyof, ksuid, lazy, _length as length, literal, index_d_exports$2 as locales, looseObject, looseRecord, _lowercase as lowercase, _lt as lt, _lte as lte, mac, map, _maxLength as maxLength, _maxSize as maxSize, memoizer, meta, _mime as mime, _minLength as minLength, _minSize as minSize, _multipleOf as multipleOf, nan, nanoid, nativeEnum, _negative as negative, never, _nonnegative as nonnegative, nonoptional, _nonpositive as nonpositive, _normalize as normalize, _null as null, nullable, nullish, number$1 as number, object, optional, output, _overwrite as overwrite, parse, parseAsync, partialRecord, pipe, _positive as positive, prefault, preprocess, prettifyError, promise, _properties as properties, _property as property, readonly, record, refine, _regex as regex, regexes_d_exports as regexes, registry, safeDecode, safeDecodeAsync, safeEncode, safeEncodeAsync, safeParse, safeParseAsync, set, setErrorMap, _size as size, _slugify as slugify, _startsWith as startsWith, strictObject, string$1 as string, stringFormat, stringbool, success, superRefine, symbol, templateLiteral, toJSONSchema, _toLowerCase as toLowerCase, _toUpperCase as toUpperCase, toZod, transform, treeifyError, _trim as trim, tuple, uint32, uint64, ulid, _undefined as undefined, union, unknown, _uppercase as uppercase, url, util_d_exports as util, uuid, uuidv4, uuidv6, uuidv7, validate, validateAsync, _void as void, withParser, xid, xor };
 }
 //#endregion
-//#region ../core/dist/change-flow-i6vGyxUm.d.mts
+//#region ../core/dist/change-flow-mr6T-6nU.d.mts
+//#region src/config-hooks.d.ts
+/**
+ * Test-only pauses inside `ConfigStore.convertToVersion3`, for the tests that prove a write racing the conversion is
+ * neither lost nor let in between its scan and its write.
+ *
+ * Deliberately not exported from the package root, as `enableNamesMigrationForTests` is not (`release-gate.ts`): a
+ * store is given them through its constructor under this symbol, which only a test importing this file by path can
+ * name. No consumer of the package can reach it.
+ */
+declare const CONVERSION_HOOKS: unique symbol;
+interface ConversionHooks {
+  /** After the read before the lock, before the config lock is taken. */
+  beforeLock?: (() => Promise<void> | void) | undefined;
+  /** Under the lock, after the approvals were scanned and before the version-3 write is built. */
+  afterScan?: (() => Promise<void> | void) | undefined;
+  /** Under the lock, immediately before the version-3 write. */
+  beforeWrite?: (() => Promise<void> | void) | undefined;
+}
 interface RegisteredServer {
   client: string;
   path: string;
@@ -4351,6 +4369,20 @@ interface ResolvedPaths {
    */
   downloadsDir: string;
 }
+type ErrorCode = "UNEXPECTED" | "APPROVAL_REQUIRED" | "APPROVAL_PENDING" | "APPROVAL_EXPIRED" | "APPROVAL_VOID" | "SEND_OUTCOME_UNKNOWN" | "SEND_REFUSED" | "POLICY_NEVER" | "RATE_CAPPED" | "UNSENDABLE_HTML" | "LOOSENING_REFUSED" | "UPDATE_REQUIRED" | "USAGE" | "CURSOR_MISMATCH" | "BAD_DATA" | "REPLY_INVALID" | "NOT_FOUND" | "PROVIDER_UNAVAILABLE" | "SECRET_STORE_UNAVAILABLE" | "TRANSIENT" | "KEYCHAIN_APPROVAL_PENDING" | "LOCK_TIMEOUT" | "AUTH_REQUIRED" | "SCOPE_MISSING" | "CONFIG";
+interface CommsErrorOptions {
+  hint?: string;
+  details?: Record<string, unknown>;
+  cause?: unknown;
+}
+declare class CommsError extends Error {
+  readonly code: ErrorCode;
+  readonly hint: string | undefined;
+  readonly details: Record<string, unknown> | undefined;
+  constructor(code: ErrorCode, message: string, options?: CommsErrorOptions);
+  get exitCode(): number;
+  get retryable(): boolean;
+}
 //#endregion
 //#region src/cli-command.d.ts
 /**
@@ -4768,7 +4800,49 @@ interface ConfigV2 extends ConfigBody {
    */
   organisations?: Record<string, OrganisationRecord> | undefined;
 }
-type Config$1 = ConfigV1 | ConfigV2;
+/** What a legacy drain records of one tracked record: still open, or what became of it. */
+type LegacyDrainOutcome = "revoked" | "expired" | "used" | "failed" | "sending" | "unknown";
+/**
+ * The approvals an earlier release prepared that were still waiting, or already being sent, when this configuration
+ * became version 3, and what has become of each (design 2026-10-05 §D1, "Old releases are locked out before the fence
+ * is relied on").
+ */
+interface LegacyDrain {
+  /** When the conversion that opened the drain was written. */
+  since: string;
+  /**
+   * Every tracked version-1 send record by id: `open` until it has an outcome — or `sending` from the start, for one an
+   * earlier release was already sending when the conversion ran.
+   */
+  tracked: Record<string, "open" | LegacyDrainOutcome>;
+}
+/** What version 3 adds to a body of either naming. */
+interface Version3Fields {
+  /** Each owner's send epoch by id; absent reads as 0. Raised by every write that turns its send policy to `never`. */
+  sendEpochs?: Record<string, number> | undefined;
+  /** Present while records from an earlier release are being retired. */
+  legacyDrain?: LegacyDrain | undefined;
+}
+/** Version 3 over a version-1 body: one plain word per account. */
+interface ConfigV3Naming1 extends ConfigBody, Version3Fields {
+  version: 3;
+  naming: 1;
+}
+/** Version 3 over a version-2 body: `organisation/platform` names, and the names they replaced. */
+interface ConfigV3Naming2 extends Omit<ConfigV2, "version">, Version3Fields {
+  version: 3;
+  naming: 2;
+}
+/**
+ * Version 3: the send epoch and the legacy drain (design 2026-10-05 §D1), over either naming — converted from version 1
+ * or 2 without renaming anything, so its body keeps the rules of the version it came from.
+ */
+type ConfigV3 = ConfigV3Naming1 | ConfigV3Naming2;
+type Config$1 = ConfigV1 | ConfigV2 | ConfigV3;
+/** A configuration whose accounts are named `organisation/platform`: version 2, or version 3 over it. */
+type NamedConfig = ConfigV2 | ConfigV3Naming2;
+/** A configuration whose accounts have one plain word each: version 1, or version 3 over it. */
+type PlainConfig = ConfigV1 | ConfigV3Naming1;
 /** The committed config returned by an update; process-only commit metadata is deliberately stored out of band. */
 type ConfigUpdateResult = Config$1;
 declare class ConfigStore {
@@ -4780,6 +4854,8 @@ declare class ConfigStore {
    */
   constructor(configDir: string, options?: {
     readonly handoffs?: CliHandoffs | undefined;
+    /** Test-only pauses inside the version-3 conversion (`config-hooks.ts`); unreachable from the package root. */
+    readonly [CONVERSION_HOOKS]?: ConversionHooks | undefined;
   });
   /** The current config; an empty one when the file does not exist yet. */
   load(): Promise<Config$1>;
@@ -4817,11 +4893,31 @@ declare class ConfigStore {
    *
    * The file it replaces is copied beside it first — see `backUpBeforeMigration` — and the copy's path returned.
    */
-  migrateNames(expected: string, rows: readonly RenamedAccount[], build: (current: ConfigV1) => ConfigV2): Promise<{
+  migrateNames(expected: string, rows: readonly RenamedAccount[], build: (current: PlainConfig) => NamedConfig): Promise<{
     status: "migrated" | "already-migrated";
-    config: ConfigV2;
+    config: NamedConfig;
     backup?: string;
   }>;
+  /**
+   * The one way a configuration becomes version 3 (design 2026-10-05 §D1, "Old releases are locked out before the
+   * fence is relied on").
+   *
+   * Version 3 carries the send epoch, which 0.13 does not know, and 0.13 refuses to read it — so from this write on, no
+   * 0.13 process can start a prepare, a claim, an approval or a policy change through this file. Nothing is renamed:
+   * a version-1 body stays version 1's (`naming: 1`) until the names migration, which needs its own approval.
+   *
+   * Under the config lock, the file is read again — never from the cache, never from the read before the lock — and an
+   * existing version 3 returned unchanged: a second converter that lost the race keeps the winner's epochs and drain.
+   * `scan` runs under the same lock, so a record written while this waited for it is seen, and an update cannot land
+   * between the scan and the write; the version-3 write carries `legacyDrain` only when the scan tracked something.
+   * With no config file at all there is nothing to convert, and nothing is written.
+   */
+  convertToVersion3(scan: () => Promise<LegacyDrain["tracked"]>, options?: {
+    now?: (() => Date) | undefined;
+  }): Promise<{
+    status: "converted" | "already" | "empty";
+    config: Config$1;
+  }>;
 }
 /** One account's rename, as the migration planned it. */
 interface RenamedAccount {
@@ -4883,6 +4979,373 @@ interface LooseningConsent {
    */
   changes?: readonly Loosening[] | undefined;
 }
+//#endregion
+//#region src/approval-binding.d.ts
+/**
+ * What a version-2 approval binds, defined once (design 2026-10-05 §D1, "Digest integrity").
+ *
+ * A record stores two digests. `contentDigest` is the outward content or change, computed as before: the message, the
+ * change, the download. `bindingDigest` is this module's: the content digest together with the record's route, its
+ * lifetimes and its own identity — who it belongs to, which draft, which channel, which send epoch. Every one of those
+ * is a field a claim or a report acts on, so a record whose binding no longer recomputes from its own fields has been
+ * altered since it was made, and nothing it says can be trusted.
+ *
+ * There is no second copy of anything: the binding is recomputed from the stored fields alone, never stored apart
+ * from them as a key.
+ */
+/**
+ * How an approval is decided, fixed when it is made: `chat` — a yes in the conversation is enough — or `confirm` — a
+ * person outside the chat decides. A send's route is the stricter of its live send policy and any escalation; a
+ * change's is the live change policy. It never changes when the configuration does.
+ */
+type ApprovalRoute = "chat" | "confirm";
+/**
+ * What a record's `inboxId` names. `owner` — a mailbox or account that existed when it was made (every send and
+ * download, and a change to one). `prospective` — a change that creates its owner, which has no id yet. `global` — a
+ * change to no owner at all, stored with `inboxId: ''`.
+ */
+type OwnerScope = "owner" | "prospective" | "global";
+/**
+ * The file operations a lock is made of, one method each, so a test can count and interrupt every one of them: the
+ * create that is the attempt, the read that checks a holder, the touch that renews, the unlink that releases.
+ * `withFileLock` uses the real ones; `tryFileLock` takes another for a caller whose every step is counted.
+ */
+interface LockIo {
+  /** Creates `path` exclusively (`wx`, 0600) holding `body`: the one attempt to take the lock. */
+  create(path: string, body: string): Promise<void>;
+  /** The lock file's text: a holder's body. */
+  read(path: string): Promise<string>;
+  /** The lock file's modification time, in milliseconds: where a renewal shows. */
+  mtime(path: string): Promise<number>;
+  /** Sets the lock file's times to now: a renewal. */
+  touch(path: string): Promise<void>;
+  rename(from: string, to: string): Promise<void>;
+  link(from: string, to: string): Promise<void>;
+  /** Removes a lock file, or one moved aside; a missing one is no error. */
+  remove(path: string): Promise<void>;
+}
+//#endregion
+//#region src/approval-io.d.ts
+/**
+ * The file operations approval maintenance and the unsent report are made of (design 2026-10-05 §D9), one method
+ * each, so that a test can count every one of them — every directory read, metadata stat, record open, lock try,
+ * renewal, ownership check and unlink — and none is hidden behind a helper. The store passes the real ones unless it
+ * was opened with others.
+ *
+ * Only these two passes go through it: every other read and write of the store is as it was.
+ */
+interface ApprovalIo {
+  /** One enumeration of a directory: its entries' names. */
+  readdir(directory: string): Promise<string[]>;
+  /** One metadata stat: the modification time, in milliseconds. */
+  stat(path: string): Promise<{
+    readonly mtimeMs: number;
+  }>;
+  /** One open of a file's content, as text. */
+  readText(path: string): Promise<string>;
+  /** Replaces a file atomically — a temporary file, flushed, renamed — and, when `durable`, syncs its directory too. */
+  writeAtomic(path: string, text: string, options?: {
+    durable?: boolean;
+  }): Promise<void>;
+  /** One unlink of an approval artifact: a record or its claim marker. A missing one rejects with `ENOENT`. */
+  unlink(path: string): Promise<void>;
+  /** The lock files' own operations (`tryFileLock`). */
+  readonly lock: LockIo;
+}
+/** A version-1 record, as 0.13.0 wrote it: a send has no `kind`, and one `digest` stands for the content. */
+interface LegacyApprovalRecord {
+  approvalId: string;
+  /** Absent on a send. */
+  kind?: ApprovalKind | undefined;
+  digestVersion: 1;
+  inboxId: string;
+  inboxSub?: string | undefined;
+  draftId: string;
+  draftMessageId: string;
+  digest: string;
+  approvedDigest?: string | undefined;
+  approvedVia?: ApprovalChannel | undefined;
+  policy: SendPolicy;
+  requiredPolicy: SendPolicy;
+  riskFlags: string[];
+  expect: Expectation;
+  challengeHash?: string | undefined;
+  challengeAttempts: number;
+  state: ApprovalState;
+  createdAt: string;
+  expiresAt: string;
+  updatedAt: string;
+  sentMessageId?: string | undefined;
+  reason?: string | undefined;
+  change?: ChangeBinding | undefined;
+  download?: DownloadBinding | undefined;
+}
+/**
+ * A version-1 record as every surface shows it: `{ approvalId, kind, state, legacy: true, createdAt, expiresAt }` and
+ * the summary a version-2 record shows — its owner, what it was for, and which channel made it when that can be told.
+ * Never claimable, and never given a version-2 timestamp it does not hold.
+ */
+interface LegacyView {
+  readonly approvalId: string;
+  readonly kind: ApprovalKind;
+  /** Derived as 0.13.0 derived it (`deriveLegacyV1State`). */
+  readonly state: ApprovalState;
+  readonly legacy: true;
+  readonly createdAt: string;
+  readonly expiresAt: string;
+  /** The stored owner, trusted as stored: a version-1 record has no binding to check it against. */
+  readonly inboxId: string;
+  readonly ownerScope: "owner" | "global";
+  /**
+   * The channel that made it, when only one could have: an `ibx_` owner is a Gmail mailbox, an `acc_` owner the
+   * stored platform of an account that still exists. Null when nothing says — it then takes part in no channel's
+   * grouping and gets only generic wording.
+   */
+  readonly channel: string | null;
+  readonly expect: Expectation;
+  readonly reason?: string | undefined;
+  readonly sentMessageId?: string | undefined;
+}
+//#endregion
+//#region src/audit.d.ts
+/**
+ * Every mailbox write leaves one line here: what was done, to which inbox, with which ids and outcome. Never message
+ * bodies, never secrets — recipient *domains* only, so the log can be shared when asking for help.
+ */
+interface AuditRecord {
+  at: string;
+  /** Immutable inbox id; `alias` is the label at the time. */
+  inboxId: string;
+  alias?: string;
+  operation: string;
+  /** `started` marks the first half of a change recorded before it is made; a later record for the same ids ends it. */
+  outcome: "ok" | "refused" | "failed" | "started";
+  ids?: Record<string, string | string[] | CondensedIds>;
+  recipientDomains?: string[];
+  /**
+   * Full canonical recipient addresses. Only a send writes these: for every other operation the domains are enough,
+   * and storing less is better — but when mail has actually left, "who did it go to" is the first question anyone
+   * asks afterwards, and a domain does not answer it.
+   */
+  recipients?: string[];
+  approvalId?: string;
+  reason?: string;
+  surface?: "cli" | "mcp";
+  /**
+   * The policy that decided how this was approved. Written by change approvals, where it is the whole question
+   * afterwards: a loosening a person typed a code for and one an agent claimed after a yes in chat look the same in
+   * the configuration, and only this line tells them apart.
+   */
+  policy?: SendPolicy;
+  /**
+   * What daily retention deleted (`operation: 'approval.retained'`, design 2026-10-05 §D9): the approval's kind, its
+   * final state, when it finished and any provider id — never its content or a recipient. Appended durably before the
+   * record is unlinked, so the audit log keeps the terminal history the approval directory no longer does.
+   */
+  retained?: RetainedApproval;
+}
+/** Large id lists are condensed so every audit line stays small enough to be appended atomically. */
+interface CondensedIds {
+  count: number;
+  sha256: string;
+  first: string[];
+}
+declare class AuditLog {
+  #private;
+  readonly directory: string;
+  constructor(stateDir: string, now?: () => Date);
+  append(record: Omit<AuditRecord, "at"> & {
+    at?: string;
+  }, options?: {
+    durable?: boolean;
+  }): Promise<AuditRecord>;
+  /** The most recent records, newest last, optionally filtered by inbox and a lower time bound. */
+  tail(options?: {
+    limit?: number;
+    inbox?: string;
+    since?: string;
+  }): Promise<AuditRecord[]>;
+}
+/** The step of a batch that failed. */
+type MaintenanceStep = "lock" | "state" | "enumerate" | "stat" | "read" | "write" | "append" | "claim-unlink" | "record-unlink" | "lock-lost" | "cursor";
+/** A failure a batch met: which step, for which record, and the error's code — never anything a record holds. */
+interface MaintenanceError {
+  readonly step: MaintenanceStep;
+  readonly approvalId?: string | undefined;
+  readonly code: string;
+}
+/**
+ * What one call of `ensurePruned` did. `attempted` — it ran a batch; when it did not, `skipped` says why: not due
+ * (a batch ran less than a day ago), busy (another process holds the maintenance lock), or no records (there is no
+ * approvals directory at all). `processed` counts the slots whose record work ran to its end, `pruned` the records
+ * deleted, `skippedBusy` the records whose lock was held elsewhere and were left. `complete` — the batch reached the end
+ * of the directory inside both bounds; hitting 200 slots or the deadline, or losing the lock, leaves it false.
+ */
+interface MaintenanceStatus {
+  readonly attempted: boolean;
+  readonly processed: number;
+  readonly pruned: number;
+  readonly skippedBusy: number;
+  readonly complete: boolean;
+  readonly errors: readonly MaintenanceError[];
+  readonly skipped?: "not-due" | "busy" | "no-records" | undefined;
+}
+/** What a batch reports of a record it is about to delete: never a body, an address, or anything a sender wrote. */
+interface RetainedApproval {
+  readonly kind: ApprovalKind;
+  readonly state: ApprovalState;
+  /** When it finished: its validated terminal time, or a legacy used record's safe `updatedAt`. */
+  readonly finishedAt: string;
+  /** A used send's provider id, when it has a non-empty one. */
+  readonly providerId?: string | undefined;
+  /** A record an earlier release wrote. */
+  readonly legacy?: true | undefined;
+}
+interface MaintenanceOptions {
+  /**
+   * When no further step may start, on the store's clock, in milliseconds: five seconds from the call when left out.
+   * A report passes the one deadline it shares with its own reads.
+   */
+  readonly deadline?: number | undefined;
+}
+//#endregion
+//#region src/approval-validate.d.ts
+/**
+ * The integrity check of a version-2 approval record (design 2026-10-05 §D1, "Digest integrity" and "Version-2
+ * timestamps fail closed"). Pure: it reads the record and the id its file is named by, and decides.
+ *
+ * A record either passes, or is `corrupt` for one fixed reason — never a sentence built from the record, so nothing a
+ * file holds is ever echoed — and of one of two attribution classes. `verified`: its `bindingDigest` recomputes, so its
+ * owner and identity can be trusted and it is corrupt for another reason (a state, a timestamp, its evidence).
+ * `unverifiable`: its binding is missing, malformed or does not match, or it sits in another record's file, so nothing
+ * it says about whom it belongs to can be trusted.
+ *
+ * Nothing here is wired into a read yet; the store's decoder does that.
+ */
+/** Why a version-2 record is corrupt: a fixed category, never the record's own words. */
+type IntegrityReason = "file-name-mismatch" | "binding-missing" | "binding-malformed" | "binding-mismatch" | "wrong-shape" | "digest-version" | "content-digest-malformed" | "content-digest-mismatch" | "identity-contradiction" | "listing-mismatch" | "state-impossible" | "lifetime-mismatch" | "timestamp-invalid" | "timestamp-missing" | "timestamp-misplaced" | "timestamp-misordered" | "sent-id-missing" | "evidence-missing" | "evidence-invalid" | "evidence-contradictory";
+type Attribution = "verified" | "unverifiable";
+//#endregion
+//#region src/approval-stored.d.ts
+/**
+ * Every approval file, read one way (design 2026-10-05 §D2, "Legacy version-1 records, one decoder everywhere" and
+ * "Two classes of parseable corrupt record").
+ *
+ * A file is one of four things, and every read says which:
+ *
+ * - `v2` — a version-2 record that passed `validateV2`: the only form anything may act on;
+ * - `legacy` — a structurally valid version-1 record, read by its own release's rules: reported, never claimed;
+ * - `corrupt` — a parseable version-2 record that failed its integrity check, attributable to its owner or not;
+ * - `unreadable` — a file that cannot safely be read at all: shown only as a stub naming its id (from the file name)
+ *   and a fixed reason, never anything the file holds.
+ *
+ * Nothing is silently omitted, and the decoder writes nothing.
+ */
+/** Why a file cannot safely be read: a fixed category, never the file's own bytes. */
+type UnreadableReason = "invalid-json" | "truncated" | "missing-ownership" | "missing-kind" | "wrong-shape" | "file-name-mismatch";
+/** What may be said of a record that cannot be trusted: its id, that it is corrupt, and why — nothing else. */
+interface CorruptStub {
+  readonly approvalId: string;
+  readonly state: "corrupt";
+  readonly reason: UnreadableReason | IntegrityReason;
+}
+/** What an attribution-verified corrupt record may still show its owner: the fields its binding was made over. */
+interface SafeFields {
+  readonly kind: ApprovalKind;
+  readonly channel: string;
+  readonly ownerScope: OwnerScope;
+  readonly inboxId: string;
+  readonly inboxSub?: string | undefined;
+  readonly draftId: string;
+  readonly draftMessageId: string;
+  readonly expect: Expectation;
+}
+type StoredApproval = {
+  readonly form: "v2";
+  readonly record: ApprovalRecord;
+} | {
+  readonly form: "legacy";
+  readonly view: LegacyView;
+  readonly record: LegacyApprovalRecord;
+} | {
+  readonly form: "corrupt";
+  readonly approvalId: string;
+  readonly reason: IntegrityReason;
+  readonly attribution: Attribution;
+  /** Only when attribution is verified. */
+  readonly safe: SafeFields | null;
+} | {
+  readonly form: "unreadable";
+  readonly stub: CorruptStub;
+};
+//#endregion
+//#region src/approval-outcome.d.ts
+/**
+ * One locked classification of every record into an outcome (design 2026-10-05 §D2).
+ *
+ * `approvalOutcome` says what a record is now — its state, whether it can be claimed, and what an action on it would be
+ * told — from the record as it was read under its own lock and the configuration read in that same lock (`LiveGate`).
+ * Nothing here reads a file or a clock of its own, and nothing here writes: the store persists what the outcome
+ * derives, and only from inside the lock it was classified under.
+ */
+/** What is being done with the record: an approval, a claim, a wait, a revoke, or a look. */
+type OutcomeAction = "approve" | "claim" | "wait" | "revoke" | "inspect";
+/** A record's state as anyone may be told it: a download's answered question says `answered`. */
+type PublicApprovalState = ApprovalState | "corrupt" | "answered";
+/**
+ * Where an approval stands, as every surface may show it (design 2026-10-05 §D8): its id, kind, channel, state and
+ * whether it can be claimed, with the timestamps its state carries. Never a challenge hash, and nothing a sender wrote.
+ */
+interface ApprovalObject {
+  readonly id: string;
+  readonly kind: ApprovalKind | null;
+  readonly channel: string | null;
+  readonly state: PublicApprovalState;
+  readonly claimable: boolean;
+  readonly route?: ApprovalRoute | undefined;
+  readonly ownerRemoved?: true | undefined;
+  /** A record from an earlier release, read by its own rules: shown, never claimed. */
+  readonly legacy?: true | undefined;
+  readonly reason?: string | undefined;
+  readonly createdAt?: string | undefined;
+  readonly expiresAt?: string | undefined;
+  readonly approvedAt?: string | undefined;
+  readonly usableUntil?: string | undefined;
+  readonly sendingAt?: string | undefined;
+  readonly sendingHeartbeatAt?: string | undefined;
+  /** When a `sending` record reads `unknown` (`unknownAtOf`): derived, never stored. Also on an `unknown` one. */
+  readonly unknownAt?: string | undefined;
+  readonly usedAt?: string | undefined;
+  readonly sentAt?: string | undefined;
+  readonly sentMessageId?: string | undefined;
+  readonly failedAt?: string | undefined;
+  readonly revokedAt?: string | undefined;
+  readonly expiredAt?: string | undefined;
+}
+/** What an action on a record is, now. */
+interface ApprovalOutcome {
+  readonly state: PublicApprovalState;
+  readonly claimable: boolean;
+  readonly ownerRemoved?: true | undefined;
+  readonly reason?: string | undefined;
+  /**
+   * A version-2 record as this classification reads it: with a revocation it derived applied (an owner removed, a
+   * stale send epoch, or — for a claim or an approval — a live `never`). Null for every other form.
+   */
+  readonly record: ApprovalRecord | null;
+  /** Whether `record` carries a revocation the classification derived, for a locked action to persist. */
+  readonly revokes: boolean;
+  /** Where it stands, as D8 shows it (`publicApproval`). */
+  readonly approval: ApprovalObject;
+  /** What the action is refused with, when it is refused by the record's state alone. */
+  readonly error?: CommsError | undefined;
+}
+/**
+ * What became of a used send, in the words of the surface that says it, from the time the provider accepted it (D2's
+ * used-send row): Gmail and Slack, where acceptance is sending, say it was "sent at …"; Resend's own surfaces that it
+ * was "accepted by Resend at …"; core's generic surfaces "accepted by <provider> at …".
+ */
+type UsedSaid = (usedAt: string) => string;
 /**
  * Why a saved name has {@link DOWNLOAD_SUFFIX} after it: a name tools read or run on their own (`auto-read`), an
  * extension that is not one of the inert ones (`type`), or no extension at all (`no-extension`).
@@ -5032,19 +5495,54 @@ interface Expectation {
 }
 interface ApprovalRecord {
   approvalId: string;
-  /** Absent on a send, so a send's record is byte for byte what it was before change approvals existed. */
-  kind?: ApprovalKind | undefined;
+  /** What it permits. Every version-2 record says, a send included; only a version-1 send was written without one. */
+  kind: ApprovalKind;
   digestVersion: number;
+  /** The manifest channel that made it (`gmail`, `slack`, `resend`, `whatsapp`, `core`), checked at creation. Bound. */
+  channel: string;
+  /** What `inboxId` names: an owner that existed, one the change creates, or none at all. Bound. */
+  ownerScope: OwnerScope;
+  /** A send's or a change's route, fixed at creation: a yes in the chat, or a person outside it. Bound. */
+  route?: ApprovalRoute | undefined;
+  /** How long it stays pending, from creation. Bound. */
+  pendingMs: number;
+  /** A send's or a change's lifetime once approved. Bound. */
+  approvedMs?: number | undefined;
   /** For a change: the id of the inbox or account it is about, or empty for one to the whole configuration. */
   inboxId: string;
   inboxSub?: string | undefined;
   draftId: string;
   /** Changes on every save of the draft; binding to it detects any edit, even one that restores identical content. */
   draftMessageId: string;
-  digest: string;
-  /** The digest the human was actually shown when approving through a confirm channel. */
+  /** The outward content or change: the message, change or download digest. */
+  contentDigest: string;
+  /** The SHA-256 of everything the record binds (`bindingDigestOf`), recomputed from its own fields on every read. */
+  bindingDigest: string;
+  /** On a send: the owner's send epoch as it was read at prepare. Bound. */
+  sendEpoch?: number | undefined;
+  /**
+   * A download's answer, bound: SHA-256 of canonical `{ bindingDigest, answer }`, written when a person answered at a
+   * terminal or in a trusted form. Never on a send or a change, which carry `approvedBindingDigest` instead.
+   */
   approvedDigest?: string | undefined;
+  /** Where a person approved, or answered: the terminal, or a trusted client's form. Absent on a chat-route claim. */
   approvedVia?: ApprovalChannel | undefined;
+  /** A send's or a change's approval: when, and the binding the person approved, which must still be the record's. */
+  approvedAt?: string | undefined;
+  /** `approvedAt + approvedMs`: until when an approved send or change may be claimed. */
+  usableUntil?: string | undefined;
+  approvedBindingDigest?: string | undefined;
+  /** When a send was claimed for sending. Kept on every state after it. */
+  sendingAt?: string | undefined;
+  /** The sending claimant's latest lease renewal, when it has made one. */
+  sendingHeartbeatAt?: string | undefined;
+  /** When a record was used: for a send, the moment the provider accepted it, and equal to `sentAt`. */
+  usedAt?: string | undefined;
+  sentAt?: string | undefined;
+  failedAt?: string | undefined;
+  revokedAt?: string | undefined;
+  /** The boundary that applied when it expired — or, on a `clock-anomaly` expiry, the time the clock was seen. */
+  expiredAt?: string | undefined;
   /** Live policy at prepare time, for display and audit. */
   policy: SendPolicy;
   /** `confirm` when risk escalation raised this send. The effective policy is the stricter of this and the live one. */
@@ -5060,23 +5558,29 @@ interface ApprovalRecord {
   updatedAt: string;
   sentMessageId?: string | undefined;
   reason?: string | undefined;
-  /** For a change: exactly what it permits. `digest` is `changeDigest` of this. */
+  /** For a change: exactly what it permits. `contentDigest` is `changeDigest` of this. */
   change?: ChangeBinding | undefined;
-  /** For a download's question: what it asked about, and the folders it offered. `digest` is `downloadDigest`. */
+  /** For a download's question: what it asked about, and the folders it offered. `contentDigest` is `downloadDigest`. */
   download?: DownloadBinding | undefined;
 }
 interface CreateApprovalInput {
+  /** The manifest channel preparing the send. A channel this release does not know is refused. */
+  channel: string;
   inboxId: string;
   inboxSub?: string | undefined;
   draftId: string;
   draftMessageId: string;
-  digest: string;
+  contentDigest: string;
+  /** The owner's send epoch, read from the configuration at prepare (`sendEpochOf`). */
+  sendEpoch: number;
   policy: SendPolicy;
   requiredPolicy: SendPolicy;
   riskFlags: string[];
   expect: Expectation;
 }
 interface CreateChangeApprovalInput {
+  /** The manifest channel of the surface preparing the change: `core` for core's own. */
+  channel: string;
   change: ChangeBinding;
   /** The change policy in force before the change: it decides how the change is approved. */
   policy: ChangePolicy;
@@ -5089,7 +5593,7 @@ interface LiveChange {
 /** What the caller observed in the live draft at the moment of a transition. */
 interface LiveDraft {
   draftMessageId: string;
-  digest: string;
+  contentDigest: string;
 }
 /** What the product making a claim tells the store about itself. */
 interface ClaimOptions {
@@ -5109,6 +5613,11 @@ interface ClaimOptions {
    * names no product at all rather than the wrong one.
    */
   pendingHint?: string | undefined;
+  /**
+   * How a used send is said in the refusal of a claim of it — the surface's own words, as `pendingHint` is (design
+   * 2026-10-05 §D2's used-send row): "sent at …" when left out, as Gmail and Slack say it.
+   */
+  usedSaid?: UsedSaid | undefined;
   /**
    * The caller's cancellation — an MCP request's signal — asked under the record's lock, immediately before the claim
    * would change the record.
@@ -5121,19 +5630,124 @@ interface ClaimOptions {
    */
   signal?: AbortSignal | undefined;
 }
+/** What a send's claim gives its claimant: the record, and the private token only the claimant holds (`heartbeat`, `fence`, `complete`). */
+interface SendClaim {
+  readonly record: ApprovalRecord;
+  /**
+   * 16 random bytes, hex: kept only in the claim's `O_EXCL` marker beside the record, and handed only to the call
+   * that claimed. Never in a record, a view, an approval object, an audit row, an error or a result.
+   */
+  readonly claimToken: string;
+  /** Where the approval stands now that it is claimed (design 2026-10-05 §D8): `sending`, never claimable. */
+  readonly approval: ApprovalObject;
+}
+/** A send's outcome, as only its claimant records it. */
+type SendOutcome = {
+  readonly sentMessageId: string;
+} | {
+  readonly error: string;
+};
+/**
+ * Whose decision a revoke carries, which decides what it may do to a record from an earlier release (version 1).
+ *
+ * `person` — a person cancelled it, from a tool, a command or a terminal. `lifecycle` — the owner it belongs to is being
+ * removed, which a person approved. Either retires a version-1 record in its own shape (`revokeLegacy`), so a running
+ * earlier release can no longer claim it. `integrity` — this release found the record does not match what it binds:
+ * that never rewrites a version-1 record, which this release cannot judge by its own rules, and gets the version
+ * refusal instead. For a version-2 record all three revoke alike.
+ */
+type RevokeDisposition = "person" | "lifecycle" | "integrity";
+/**
+ * What a caller takes an id to be: an approval of `kind` (any kind when left out); on a channel's own surface that is
+ * no one owner's — its terminal approval — one of `channel`'s, the manifest channel that prepared it; and on a surface
+ * pinned to one mailbox or account, or a claim made for one, owned by `owner`. Anything else is the one `NOT_FOUND`
+ * (`approvalNotFound`), checked before the record's state is looked at: another channel's send given to Gmail's
+ * `approve` is not found there, as one nobody prepared is not (design 2026-10-05 §D2).
+ */
+interface ApprovalExpectation {
+  readonly kind?: ApprovalKind | undefined;
+  readonly channel?: string | undefined;
+  readonly owner?: string | undefined;
+}
+/** How the store is opened. */
+interface ApprovalStoreOptions {
+  now?: () => Date;
+  handoffs?: CliHandoffs | undefined;
+  /**
+   * The configuration, read afresh: the one thing a read of the store consults beyond the files themselves — to
+   * attribute a version-1 record whose owner is an account to that account's platform, and for every locked
+   * transition, the live gate it classifies by (`liveGateOf`): the owner, its policies and its send epoch. Read once
+   * per `get`, once per `list`, and once per locked transition after its lock is held, so one call decodes and
+   * classifies against one snapshot. Its errors propagate: a configuration that cannot be read is never taken for none.
+   * Resolving `null`, or left out, is "no configuration": a version-1 account record is then unattributable, nothing is
+   * ever claimable, and a claim, an approval or an answer is refused with `CONFIG`.
+   */
+  loadConfig?: (() => Promise<Config$1 | null>) | undefined;
+  /**
+   * The audit log daily retention records each deletion in (`approval.retained`, design 2026-10-05 §D9): the state
+   * directory's own when left out. `openCore` passes the one it opens.
+   */
+  audit?: Pick<AuditLog, "append"> | undefined;
+  /**
+   * The file operations daily maintenance and the unsent report go through — the real ones when left out; a test's to
+   * count and interrupt every step. Every other read and write of the store is unaffected.
+   */
+  io?: ApprovalIo | undefined;
+}
 declare class ApprovalStore {
   #private;
   readonly directory: string;
-  constructor(stateDir: string, options?: {
-    now?: () => Date;
-    ttlMs?: number;
-    downloadTtlMs?: number;
-    handoffs?: CliHandoffs | undefined;
-  });
+  constructor(stateDir: string, options?: ApprovalStoreOptions);
+  /**
+   * Daily retention (design 2026-10-05 §D9): once a day per state directory, a bounded batch deletes valid finished
+   * records ninety days past their finish. Awaited before every creation, list, status and wait — with its own
+   * five-second budget — and before a report, on the report's shared deadline. Never a gate: whatever it finds, it
+   * returns its status and the caller goes on.
+   */
+  ensurePruned(options?: MaintenanceOptions): Promise<MaintenanceStatus>;
   create(input: CreateApprovalInput): Promise<ApprovalRecord>;
-  get(approvalId: string): Promise<ApprovalRecord | null>;
+  /**
+   * One approval, in whichever of its four forms it is (`StoredApproval`), read against one configuration snapshot —
+   * or null when there is none. Nothing is written.
+   */
+  get(approvalId: string): Promise<StoredApproval | null>;
+  /**
+   * A look at one approval, under its lock: the record as it stands and its classification for `expect` — the same
+   * `NOT_FOUND` as every action for an id that is not what the caller expects, before anything of the record is
+   * classified. It writes only what reading derives (an expiry, a dead send's `unknown`), never a revocation: an owner
+   * removed or a stale epoch is shown as revoked here, and written by the next action.
+   *
+   * `action` is for a surface about to act on what it reads — a terminal about to show a preview, an execute about to
+   * read its draft — classified for that action (`approve`, `claim`, `revoke`), so the refusal is the one the action
+   * would get. A revocation the classification derives for it is written then, as the action itself would write it:
+   * the first locked action persists it, and this is that action's first step (design 2026-10-05 §D2).
+   */
+  inspect(approvalId: string, expect?: ApprovalExpectation, options?: {
+    action?: OutcomeAction | undefined;
+    usedSaid?: UsedSaid | undefined;
+  }): Promise<{
+    stored: StoredApproval;
+    outcome: ApprovalOutcome;
+  }>;
+  /**
+   * D8's object for a record a call has just written, claimed or finished — what its result reports. Classified as a
+   * look at it would be, against a fresh read of the configuration, without the lock and writing nothing: what decided
+   * was the transition that wrote it. A configuration that cannot be read leaves only what the record says (nothing
+   * claimable): a report never fails the call it reports on, least of all one that has already sent.
+   */
+  approvalOf(record: ApprovalRecord): Promise<ApprovalObject>;
+  /**
+   * The classification of a record a call has just written, in any of its forms — a revoke's, a cancel's — for its
+   * result to show through `publicApproval`, as a status, a wait and a list show theirs: what a sender wrote only inside
+   * the untrusted-content envelope (design 2026-10-05 §D8). Classified as a look at it would be, against a fresh read of
+   * the configuration, without the lock and writing nothing, as `approvalOf` is; a configuration that cannot be read
+   * leaves nothing claimable, and never fails the call it reports on.
+   */
+  outcomeOf(stored: StoredApproval): Promise<ApprovalOutcome>;
   /** Issues a new challenge to show a human; only its hash is kept. */
-  issueChallenge(approvalId: string, kind?: ApprovalKind, platform?: NodeJS.Platform): Promise<string>;
+  issueChallenge(approvalId: string, kind?: ApprovalKind, _platform?: NodeJS.Platform, options?: {
+    usedSaid?: UsedSaid | undefined;
+  }): Promise<string>;
   /**
    * A human approved through a confirm channel by typing the issued challenge. The draft must still be exactly what the
    * record was prepared for; otherwise the record is voided, because the human would be approving content the record
@@ -5142,18 +5756,35 @@ declare class ApprovalStore {
    * A change is approved the same way, with `kind: 'change'` and its digest standing in for the draft (see
    * `createChange`), so a person's typed code means one thing whichever kind of approval it is typed for.
    */
-  approve(approvalId: string, via: ApprovalChannel, live: LiveDraft, answer: string, kind?: ApprovalKind, platform?: NodeJS.Platform): Promise<ApprovalRecord>;
+  approve(approvalId: string, via: ApprovalChannel, live: LiveDraft, answer: string, kind?: ApprovalKind, _platform?: NodeJS.Platform, options?: {
+    usedSaid?: UsedSaid | undefined;
+  }): Promise<ApprovalRecord>;
   /**
    * Claims the record for sending, once. Non-consuming refusals (not yet approved) leave the record untouched so the
-   * human can still approve it; integrity failures (other inbox or account, edited or changed draft, different
-   * recipients or subject) void it. Success creates the O_EXCL claim marker.
+   * human can still approve it; integrity failures (another account, an edited or changed draft, different recipients
+   * or subject) void it. Success creates the O_EXCL claim marker.
+   *
+   * `live.inboxId` is the owner the caller claims for: a record of another owner is the one `NOT_FOUND`, and left as it
+   * is. The policy is the live gate's, from the configuration read under the record's lock (decision 4): a value the
+   * caller read before the lock is exactly what a `never` change can land between.
    */
   claimForSend(approvalId: string, live: LiveDraft & {
     inboxId: string;
     inboxSub?: string | undefined;
-    policy: SendPolicy;
     expect: Expectation;
-  }, options?: ClaimOptions): Promise<ApprovalRecord>;
+  }, options?: ClaimOptions): Promise<SendClaim>;
+  /**
+   * Renews the sending lease of a send this call claimed: writes `sendingHeartbeatAt` while the claim still owns a
+   * `sending` record, and nothing otherwise. `renewed` while it is sending; `lost` once it reads `unknown` (or anything
+   * else) — a renewal never moves a record back to `sending`. Refused, writing nothing, without the claim's token.
+   */
+  heartbeat(approvalId: string, claimToken: string): Promise<"renewed" | "lost">;
+  /**
+   * The check before each provider step (design 2026-10-05 §D1): `go`, with the lease renewed, while this claim still
+   * owns a `sending` record; `stop` once it reads `unknown` — another caller has decided its outcome cannot be known,
+   * and no further step may start. Refused, writing nothing, without the claim's token.
+   */
+  fence(approvalId: string, claimToken: string): Promise<"go" | "stop">;
   /**
    * A change approval, pending, bound to `changeDigest(input.change)`.
    *
@@ -5184,6 +5815,8 @@ declare class ApprovalStore {
    * other changes are approved. A claim holds the question to the stricter of this and the policy then.
    */
   createDownload(input: {
+    /** The manifest channel the files come from. */
+    channel: string;
     download: DownloadBinding;
     policy: ChangePolicy;
   }): Promise<ApprovalRecord & {
@@ -5196,7 +5829,7 @@ declare class ApprovalStore {
    *
    * Only a pending question can be answered, and only once: a second answer is refused, not taken over the first.
    */
-  answerDownload(approvalId: string, via: ApprovalChannel, answer: RecordedSaveAnswer, platform?: NodeJS.Platform): Promise<ApprovalRecord & {
+  answerDownload(approvalId: string, via: ApprovalChannel, answer: RecordedSaveAnswer, _platform?: NodeJS.Platform): Promise<ApprovalRecord & {
     download: DownloadBinding;
   }>;
   /**
@@ -5209,17 +5842,17 @@ declare class ApprovalStore {
    * open, as it was: a second call that got an argument wrong is the agent's slip, not the person's, and voiding the
    * question for it would make the person answer again for nothing. It still expires, and is claimed once.
    *
-   * `options.policy` is the change policy of that account now, and the stricter of it and the one the question was
-   * asked under decides. Under `chat`, a pending question is claimed with the answer the caller carries: the person
-   * gave it in the conversation. Under `confirm`, only a question the person answered at a terminal or in a trusted
-   * form can be claimed; a pending one is refused, and left as it is, so they can still answer it. One used, voided or
-   * expired is refused as an approval in that state is.
+   * Whether it can be claimed is the download `claimable` matrix (`downloadClaimable`, design 2026-10-05 §D2), decided
+   * under the question's lock against the live change policy read there — never a policy the caller read before it.
+   * While both the policy the question was asked under and the live one are `chat`, a pending question is claimed
+   * with the answer the caller carries: the person gave it in the conversation, and it is never kept. Otherwise only a
+   * question the person answered at a terminal or in a trusted form can be claimed; a pending one is refused, and left
+   * as it is, so they can still answer it. One used, voided, expired or corrupt is refused for what it is.
    *
    * `options.signal` is the download's cancellation, asked under the lock as a send's is (`ClaimOptions.signal`): a
    * download cancelled while this waited saves nothing and leaves the question open, the answer still unused.
    */
   claimForDownload(approvalId: string, live: DownloadRequest, options?: {
-    policy?: ChangePolicy | undefined;
     pendingHint?: string | undefined;
     signal?: AbortSignal | undefined;
     platform?: NodeJS.Platform | undefined;
@@ -5227,72 +5860,76 @@ declare class ApprovalStore {
   }): Promise<ApprovalRecord & {
     download: DownloadBinding;
   }>;
-  /** Records the outcome of the one send attempt. */
-  complete(approvalId: string, outcome: {
-    sentMessageId: string;
-  } | {
-    error: string;
-  }): Promise<ApprovalRecord>;
-  /** Voids a pending or approved record (user revoked it, or policy tightened). Other records are left as they are. */
-  revoke(approvalId: string, reason: string): Promise<ApprovalRecord>;
-  list(filter?: {
-    inboxId?: string;
-    states?: ApprovalState[];
-  }): Promise<ApprovalRecord[]>;
-}
-//#endregion
-//#region src/audit.d.ts
-/**
- * Every mailbox write leaves one line here: what was done, to which inbox, with which ids and outcome. Never message
- * bodies, never secrets — recipient *domains* only, so the log can be shared when asking for help.
- */
-interface AuditRecord {
-  at: string;
-  /** Immutable inbox id; `alias` is the label at the time. */
-  inboxId: string;
-  alias?: string;
-  operation: string;
-  /** `started` marks the first half of a change recorded before it is made; a later record for the same ids ends it. */
-  outcome: "ok" | "refused" | "failed" | "started";
-  ids?: Record<string, string | string[] | CondensedIds>;
-  recipientDomains?: string[];
   /**
-   * Full canonical recipient addresses. Only a send writes these: for every other operation the domains are enough,
-   * and storing less is better — but when mail has actually left, "who did it go to" is the first question anyone
-   * asks afterwards, and a domain does not answer it.
+   * Records the outcome of the one send attempt: `used` with the provider's id for it, when the provider accepted it,
+   * or `failed`.
+   *
+   * `used` needs a non-empty id. A provider that accepted a send without one has not given anything to record it by,
+   * so the record is left as it is — `sending`, and then `unknown` — rather than made `used` with an empty id that
+   * every later reader would take for one.
+   *
+   * Only the claimant records it, by its claim token, from `sending` or from `unknown`: a provider's answer that
+   * arrives after the lease ran out is still the truth. A late success clears the stale-lease reason; a late failure
+   * replaces it with its own.
    */
-  recipients?: string[];
-  approvalId?: string;
-  reason?: string;
-  surface?: "cli" | "mcp";
+  complete(approvalId: string, claimToken: string, outcome: SendOutcome): Promise<ApprovalRecord>;
   /**
-   * The policy that decided how this was approved. Written by change approvals, where it is the whole question
-   * afterwards: a loosening a person typed a code for and one an agent claimed after a yes in chat look the same in
-   * the configuration, and only this line tells them apart.
+   * Voids a pending or approved record. Other records are left as they are, and returned as they read.
+   *
+   * `disposition` says whose decision this is, and has no default: every caller chooses (`RevokeDisposition`). A
+   * version-1 record is retired in its own shape when a person or an owner's removal revokes it (`revokeLegacy`), and
+   * refused with the version refusal, nothing written, when this release's integrity check would have voided it. A
+   * corrupt or unreadable record is never revoked or rewritten: it is refused with the integrity refusal, which repeats
+   * only its stub.
+   */
+  revoke(approvalId: string, reason: string, options: {
+    disposition: RevokeDisposition;
+    expect?: ApprovalExpectation | undefined;
+  }): Promise<StoredApproval>;
+  /**
+   * Retires a record from an earlier release (version 1) in that release's own shape, so a process still running it
+   * can no longer claim the record — and nothing more.
+   *
+   * Under the record's own lock, `<id>.json.lock`, the one 0.13.0's transitions take, so the two serialise. The file
+   * is read again there, decoded, and its state derived by its own release's rules (`deriveLegacyV1State`). Only a
+   * `pending` or `approved` record is rewritten, as itself plus `state: 'revoked'`, the reason and `updatedAt`: its
+   * digest version stays 1, a send stays without a `kind`, and no field of this release's is added — no claim marker
+   * either. Any other derived state is returned as it reads and written nothing: an expired record is never rewritten,
+   * as `revoke` leaves every finished record as it is.
+   *
+   * It reads no configuration and needs no owner, so it works on a record whose account is already gone. Its only
+   * callers are a person's revoke, the removal of the record's owner, and the legacy drain.
    */
-  policy?: SendPolicy;
-}
-/** Large id lists are condensed so every audit line stays small enough to be appended atomically. */
-interface CondensedIds {
-  count: number;
-  sha256: string;
-  first: string[];
-}
-declare class AuditLog {
-  #private;
-  readonly directory: string;
-  constructor(stateDir: string, now?: () => Date);
-  append(record: Omit<AuditRecord, "at"> & {
-    at?: string;
-  }, options?: {
-    durable?: boolean;
-  }): Promise<AuditRecord>;
-  /** The most recent records, newest last, optionally filtered by inbox and a lower time bound. */
-  tail(options?: {
-    limit?: number;
-    inbox?: string;
-    since?: string;
-  }): Promise<AuditRecord[]>;
+  revokeLegacy(approvalId: string, reason: string): Promise<LegacyApprovalRecord>;
+  /**
+   * Every approval file, each looked at under its own lock and classified there, as `inspect` looks at one — against one
+   * configuration snapshot, loaded once before any file is read (design 2026-10-05 §D2, §D8). What a list shows: each
+   * record's form and its outcome, nothing skipped. Like a look, it writes only what reading derives — an expiry at its
+   * boundary, a stale send's `unknown` — never a revocation: an owner removed or a stale epoch is shown as revoked, and
+   * written by the next action.
+   *
+   * `inboxId` keeps the records whose owner is that id (`ownerOf`), so one whose owner cannot be trusted never matches;
+   * `states` keeps those whose classified state is listed — a stored state, `corrupt`, and for a download's answered
+   * question its stored `approved` or `used`.
+   */
+  inspectAll(filter?: {
+    inboxId?: string;
+    states?: (ApprovalState | "corrupt")[];
+  }): Promise<Array<{
+    stored: StoredApproval;
+    outcome: ApprovalOutcome;
+  }>>;
+  /**
+   * Every approval file, each in one of its four forms — nothing skipped, nothing omitted — read against one
+   * configuration snapshot, loaded once before any file is read: a loader that fails fails the whole list.
+   *
+   * `inboxId` keeps the records whose owner is that id (`ownerOf`), so a file whose owner cannot be trusted never
+   * matches one; `states` keeps those whose state (`stateOf`, `corrupt` for one that cannot be used) is listed.
+   */
+  list(filter?: {
+    inboxId?: string;
+    states?: (ApprovalState | "corrupt")[];
+  }): Promise<StoredApproval[]>;
 }
 //#endregion
 //#region src/ledger.d.ts
@@ -5456,9 +6093,23 @@ interface TaintExclusions {
    */
   ownHandles?: readonly TaintHandle[] | undefined;
 }
+/**
+ * One stored aggregate, exactly as the store holds it (design 2026-10-05 §D4): the newest time anything matched it, the
+ * strongest source ever seen — `header` is kept once seen — and every mailbox that recorded it. Three separate facts,
+ * never one sighting: `touch` replaces the time, keeps a header and unions the mailboxes independently.
+ */
+interface TaintAggregate {
+  readonly at: string;
+  readonly source: TaintSource;
+  readonly inboxIds: readonly string[];
+}
 interface TaintCheck {
   address: boolean;
   domain: boolean;
+  /** The exact address's aggregate, when it is in the window. */
+  addressSeen?: TaintAggregate | undefined;
+  /** Its domain's, when that counts — not a public mailbox provider — and is in the window. */
+  domainSeen?: TaintAggregate | undefined;
 }
 declare class TaintStore {
   #private;
@@ -5469,7 +6120,10 @@ declare class TaintStore {
    * was not recorded.
    */
   record(observations: readonly TaintObservation[], exclusions: TaintExclusions, handleObservations?: readonly TaintHandleObservation[]): Promise<void>;
-  /** Whether an address, or its (non-public) domain, was seen in email content in the window — from any inbox. */
+  /**
+   * Whether an address, or its (non-public) domain, was seen in email content in the window — from any inbox — and the
+   * aggregate each match is made of, for a caller to explain it. Nothing is written.
+   */
   check(address: string): Promise<TaintCheck>;
   /**
    * Whether a handle was seen in message content in the window.