@coffre/vault 0.10.0 → 0.10.2

package/src/snapshot.ts

@@ -0,0 +1,191 @@
+import type { StoredEntry } from '@coffre/core/audit';
+import type { Queryable, Transaction } from '@coffre/db';
+import { LogHeadMismatch, lockLogHead } from '@coffre/db/log';
+import { engineOf, rowsOf } from '@coffre/db/dialect';
+import type { GrantRow } from '@coffre/db/grants';
+
+import { snapshotQuery as postgres } from './snapshot.postgres.ts';
+import { snapshotQuery as sqlite } from './snapshot.sqlite.ts';
+import * as store from './store.ts';
+import type { EnvironmentRow, Member } from './store.ts';
+
+/**
+ * What a decision reads, or `access`, in one statement: one round trip, and
+ * one snapshot of the database, so its parts agree with each other.
+ *
+ * In a decision, the same statement locks the log's head, but only if it
+ * is free (`SKIP LOCKED`). Postgres takes a statement's snapshot when it
+ * starts, so one that waited for the lock would have read everything but
+ * the head as it was before the wait: a policy changed, a place deleted, a
+ * grant written around the vault while it waited would be missed. A
+ * statement that never waits reads all of it as of the lock. When another
+ * transaction holds the head, the decision waits for it in a statement of
+ * its own, then reads again, holding it. The read checks that the head names
+ * the last entry it saw, too (`current`): one taken between the snapshot and
+ * the lock, by an append that committed in that instant, is read again. That
+ * check sees a commit only through the head it moved, which holds because
+ * every change a decision reads commits with an entry under the head: the
+ * vault's own decisions, and the app's writes to places, each `audited`
+ * with its entry.
+ */
+export type Snapshot = {
+  /** The database's clock, milliseconds since the epoch. */
+  at: number;
+  /** The rows of `asked.members`, by principal; those with none are not in the map. */
+  members: Map<string, Member>;
+  /** Every grant of each asked principal, lapsed ones too. */
+  grants: Map<string, GrantRow[]>;
+  /** The newest allowed access entry in the vault's name about each asked principal, unchecked. */
+  newestAccess: Map<string, StoredEntry>;
+  /** The newest allowed `policy.change` in the vault's name, unchecked. */
+  newestPolicy: StoredEntry | null;
+  /**
+   * The asked environments, the environments each personal config among
+   * them is a config of, and those the newest `policy.change` names, by id.
+   */
+  environments: Map<string, EnvironmentRow>;
+  /** Of the asked `reference.create` entries, those a `reference.end` of the vault's names, allowed. */
+  ended: Set<bigint>;
+  /**
+   * How many distinct keys `asked.released.principal` holds released within
+   * its window once it is given `asked.released.keys` too: a key released
+   * again, or asked for again, counts once.
+   */
+  released: number;
+  /** The log's head, locked, with the last entry and the newest `key.rotate`; null unless asked, or held by another. */
+  head: LockedHead | null;
+};
+
+export type LockedHead = {
+  nextSeq: bigint;
+  headHash: Buffer;
+  /** The log's last entry, as this statement's snapshot has it. */
+  last: { seq: bigint; hash: Buffer } | null;
+  /** The vault's newest `key.rotate`, allowed, unchecked. */
+  rotation: StoredEntry | null;
+};
+
+/** What to read. */
+export type Asked = {
+  /** Whose grants and newest access entry; with `members`, their rows too, unlocked. */
+  principals: readonly string[];
+  members?: boolean;
+  environments?: readonly string[];
+  references?: readonly bigint[];
+  /**
+   * One principal's releases within the last `windowMs` of the clock, moved
+   * on by `clockOffsetMs` as the vault's is, with `keys`, secret ids, besides.
+   */
+  released?: { principal: string; keys: readonly string[]; windowMs: number; clockOffsetMs: number };
+  /** Lock the log's head first. */
+  head?: boolean;
+};
+
+/** One statement's read, as `Snapshot` says; with the head, two more when another holds it. */
+export async function snapshot(tx: Transaction, asked: Asked): Promise<Snapshot>;
+export async function snapshot(db: Queryable, asked: Asked & { head?: false }): Promise<Snapshot>;
+export async function snapshot(db: Queryable, asked: Asked): Promise<Snapshot> {
+  const read = () => readOnce(db, asked);
+  const first = await read();
+  if (asked.head !== true || (first.head !== null && current(first.head))) return first;
+  // Held by another, or moved in the instant before the lock: everything again, once the head is this transaction's.
+  // Asked for the head, `db` is a transaction (the overloads above).
+  if (first.head === null) await lockLogHead(db as Transaction);
+  const again = await read();
+  if (again.head === null) throw new Error("the log's head, held by this transaction, was read as held by another");
+  // Held, nothing appends: a head that names another last entry was moved, or the log written, around it (`appendEntries`).
+  if (!current(again.head)) {
+    throw new LogHeadMismatch(`the log's head says entry ${again.head.nextSeq} comes next, but the log ends ${again.head.last === null ? 'empty' : `at entry ${again.head.last.seq}`}, or with another hash`);
+  }
+  return again;
+}
+
+/** Whether the head names the last entry the same statement saw: nothing was appended between its snapshot and its lock. */
+export function current(head: LockedHead): boolean {
+  if (head.last === null) return head.nextSeq === 0n;
+  return head.nextSeq === head.last.seq + 1n && head.headHash.equals(head.last.hash);
+}
+
+async function readOnce(db: Queryable, asked: Asked): Promise<Snapshot> {
+  const query = (engineOf(db) === 'postgres' ? postgres : sqlite)(asked);
+  const [row] = await rowsOf<{ snapshot: string | Raw }>(db, query);
+  const raw: Raw = typeof row!.snapshot === 'string' ? (JSON.parse(row!.snapshot) as Raw) : row!.snapshot;
+  return {
+    at: Number(raw.at),
+    members: new Map(raw.members.map((member) => [member.principal, memberOf(member)])),
+    grants: new Map(asked.principals.map((principal) => [principal, raw.grants.filter((grant) => grant.principal === principal).map(grantOf)])),
+    newestAccess: new Map(raw.access.map((entry) => [entry.subjectPrincipal!, entryOf(entry)])),
+    newestPolicy: raw.policy === null ? null : entryOf(raw.policy),
+    environments: new Map(raw.environments.map(({ id, ...environment }) => [id, {
+      ...environment,
+      deleted: Boolean(environment.deleted),
+      archived: Boolean(environment.archived),
+    }])),
+    ended: new Set(raw.ended.map((seq) => BigInt(seq))),
+    released: Number(raw.released ?? 0),
+    head: raw.head === null ? null : {
+      nextSeq: BigInt(raw.head.nextSeq),
+      headHash: Buffer.from(raw.head.hash, 'hex'),
+      last: raw.last === null ? null : { seq: BigInt(raw.last.seq), hash: Buffer.from(raw.last.hash, 'hex') },
+      rotation: raw.rotation === null ? null : entryOf(raw.rotation),
+    },
+  };
+}
+
+/** Whole numbers come as JSON numbers or text, bytes as hex, as each dialect's query writes them. */
+type Int = number | string;
+
+/** An entry's columns, as both dialects' queries write them (`entryJson`). */
+export type RawEntry = {
+  seq: Int; author: string; keyId: string; occurredAt: Int; actor: string; action: string; decision: string; code: string | null;
+  subjectPrincipal: string | null; projectId: string | null; environmentId: string | null; secretId: string | null;
+  secretVersionId: string | null; operationId: string | null; requestId: string | null; sourceIp: string | null;
+  relatedSeq: Int | null; metadata: string; prevHash: string; mac: string; hash: string;
+};
+
+type Raw = {
+  at: Int;
+  head: { nextSeq: Int; hash: string } | null;
+  last: { seq: Int; hash: string } | null;
+  rotation: RawEntry | null;
+  members: {
+    principal: string; status: 'active' | 'removed'; owner: boolean | number; role: string | null; scope: string | null; generation: Int;
+    createdAt: Int; createdBy: string; statusChangedAt: Int; statusChangedBy: string; accessSeq: Int; mac: string;
+  }[];
+  grants: { principal: string; projectId: string | null; environmentId: string | null; environmentSlug: string | null; role: string; expiresAt: Int | null; grantedAt: Int; grantedBy: string }[];
+  access: RawEntry[];
+  policy: RawEntry | null;
+  environments: { id: string; projectId: string; slug: string; owner: string | null; parentId: string | null; deleted: boolean | number; archived: boolean | number }[];
+  ended: Int[];
+  released: Int | null;
+};
+
+/** An entry as the chain's codec reads it, from what `entryJson` wrote. */
+export function entryOf(raw: RawEntry): StoredEntry {
+  return {
+    ...raw,
+    seq: BigInt(raw.seq),
+    author: raw.author as StoredEntry['author'],
+    occurredAt: Number(raw.occurredAt),
+    relatedSeq: raw.relatedSeq === null ? null : BigInt(raw.relatedSeq),
+    prevHash: Buffer.from(raw.prevHash, 'hex'),
+    mac: Buffer.from(raw.mac, 'hex'),
+    hash: Buffer.from(raw.hash, 'hex'),
+  };
+}
+
+function grantOf(raw: Raw['grants'][number]): GrantRow {
+  return { ...raw, expiresAt: raw.expiresAt === null ? null : Number(raw.expiresAt), grantedAt: Number(raw.grantedAt) };
+}
+
+function memberOf({ owner, ...raw }: Raw['members'][number]): Member {
+  return store.memberOf({
+    ...raw,
+    owner: owner === true || owner === 1,
+    generation: Number(raw.generation),
+    createdAt: Number(raw.createdAt),
+    statusChangedAt: Number(raw.statusChangedAt),
+    accessSeq: BigInt(raw.accessSeq),
+    mac: Buffer.from(raw.mac, 'hex'),
+  });
+}

package/src/store.ts

@@ -1,7 +1,7 @@
 import { EVERYWHERE, ownsInstance, type InstanceRole, type Scope } from '@coffre/core/access';
 import type { Author, StoredEntry } from '@coffre/core/audit';
 import { ACCESS_ACTIONS, type SecretRef, type WrappedKey } from '@coffre/core/vault';
-import { tablesOf, type Queryable, type Transaction } from '@coffre/db';
+import { prepared, tablesOf, type Queryable, type Transaction } from '@coffre/db';
 import { clockMillis, engineOf, forUpdate, tombstone, truth } from '@coffre/db/dialect';
 import { readGrants, roleColumns, storedRole, type GrantRow } from '@coffre/db/grants';
 import { entryColumns, withinBytes } from '@coffre/db/log';
@@ -61,11 +61,12 @@ export async function boundLockWaits(tx: Transaction, ms: number): Promise<void>
 
 /** The database's clock, now. */
 export async function now(db: Queryable): Promise<number> {
-  const { auditChainHead } = tablesOf(db);
-  const [{ at }] = await db.select({ at: clockMillis(db) }).from(auditChainHead);
+  const [{ at }] = await clock(db);
   return at;
 }
 
+const clock = prepared((db) => db.select({ at: clockMillis(db) }).from(tablesOf(db).auditChainHead));
+
 // --- members --------------------------------------------------------------------
 
 function memberColumns(db: Queryable) {
@@ -87,10 +88,10 @@ function memberColumns(db: Queryable) {
 }
 
 /** A row as stored: `role` and `scope` as their columns hold them. */
-type StoredMember = Omit<Member, 'role' | 'scope'> & { owner: boolean; role: string | null; scope: string | null };
+export type StoredMember = Omit<Member, 'role' | 'scope'> & { owner: boolean; role: string | null; scope: string | null };
 
 /** A member as their row says (`storedRole`). */
-function memberOf({ owner, role, scope, ...row }: StoredMember): Member {
+export function memberOf({ owner, role, scope, ...row }: StoredMember): Member {
   return { ...row, ...storedRole({ owner, role, scope }) };
 }
 
@@ -101,11 +102,15 @@ function storedChange(change: Partial<Omit<Member, 'principal'>>): Record<string
 }
 
 export async function member(db: Queryable, principal: string): Promise<Member | undefined> {
-  const { vaultMembers } = tablesOf(db);
-  const [row] = await db.select(memberColumns(db)).from(vaultMembers).where(eq(vaultMembers.principal, principal));
+  const [row] = await memberRow(db, { principal });
   return row === undefined ? undefined : memberOf(row as StoredMember);
 }
 
+const memberRow = prepared((db) => {
+  const { vaultMembers } = tablesOf(db);
+  return db.select(memberColumns(db)).from(vaultMembers).where(eq(vaultMembers.principal, sql.placeholder('principal')));
+});
+
 export async function allMembers(db: Queryable): Promise<Member[]> {
   const { vaultMembers } = tablesOf(db);
   return ((await db.select(memberColumns(db)).from(vaultMembers).orderBy(asc(vaultMembers.principal))) as StoredMember[]).map(memberOf);
@@ -303,34 +308,6 @@ export async function everyProjectHolders(db: Queryable): Promise<string[]> {
 
 // --- the log --------------------------------------------------------------------
 
-/** The action of an entry that releases a key, which the bulk limit counts. */
-export const RELEASE = 'secret.read';
-
-/**
- * How many keys the vault has released to `principal` since `after`: one
- * for an entry about one secret, and as many as it lists for one about
- * several (`secrets`), a read logged once per place.
- */
-export async function releasesSince(db: Queryable, principal: string, after: number): Promise<number> {
-  const { auditLog } = tablesOf(db);
-  const listed = engineOf(db) === 'postgres'
-    ? sql`jsonb_array_length((${auditLog.metadata})::jsonb -> 'secrets')`
-    : sql`json_array_length(${auditLog.metadata}, '$.secrets')`;
-  const [{ n }] = await db
-    .select({ n: sql<string | number | null>`SUM(COALESCE(${listed}, 1))` })
-    .from(auditLog)
-    .where(
-      and(
-        eq(auditLog.author, 'vault'),
-        eq(auditLog.actor, principal),
-        eq(auditLog.action, RELEASE),
-        eq(auditLog.decision, 'allow'),
-        gt(auditLog.occurredAt, after),
-      ),
-    );
-  return Number(n ?? 0);
-}
-
 /** Rows of the log as the chain's codec reads them: `author` and `decision` are checked by the table. */
 function stored(rows: object[]): StoredEntry[] {
   return rows as StoredEntry[];
@@ -380,17 +357,6 @@ export async function hashesAt(db: Queryable, seqs: readonly bigint[]): Promise<
 /** How many entries' hashes one query asks for: a checkpoint every five minutes is tens of thousands of a year. */
 const HASHES_AT_ONCE = 5000;
 
-/**
- * Whether every entry from the first through `seq` is there. Seqs are the
- * primary key, so the count is `seq + 1` exactly when none is missing: one
- * pass over the key's index, never the entries.
- */
-export async function complete(db: Queryable, seq: bigint): Promise<boolean> {
-  const { auditLog } = tablesOf(db);
-  const [{ n }] = await db.select({ n: count() }).from(auditLog).where(and(gte(auditLog.seq, 0n), lte(auditLog.seq, seq)));
-  return BigInt(n) === seq + 1n;
-}
-
 /** The entry at `seq`'s hash, or undefined when there is none. */
 export async function hashAt(db: Queryable, seq: bigint): Promise<Buffer | undefined> {
   const { auditLog } = tablesOf(db);
@@ -537,6 +503,82 @@ export async function latestVaultEntry(db: Queryable, actions: readonly string[]
   return row === undefined ? undefined : stored([row])[0];
 }
 
+/**
+ * The vault's newest checkpoint that keeps a tally, allowed, or undefined:
+ * one written since 0.10.1, which names the last entry of the prefix it
+ * signs as related (`related_seq`); those before name none.
+ */
+export async function latestTallied(db: Queryable): Promise<StoredEntry | undefined> {
+  const { auditLog } = tablesOf(db);
+  const [row] = await db
+    .select(entryColumns(db))
+    .from(auditLog)
+    .where(and(eq(auditLog.author, 'vault'), eq(auditLog.action, 'audit.checkpoint'), eq(auditLog.decision, 'allow'), isNotNull(auditLog.relatedSeq)))
+    .orderBy(desc(auditLog.seq))
+    .limit(1);
+  return row === undefined ? undefined : stored([row])[0];
+}
+
+/** The vault's newest `audit.checkpoint` entry, signed or refused, or undefined. */
+export async function newestCheckpointEntry(db: Queryable): Promise<StoredEntry | undefined> {
+  const { auditLog } = tablesOf(db);
+  const [row] = await db
+    .select(entryColumns(db))
+    .from(auditLog)
+    .where(and(eq(auditLog.author, 'vault'), eq(auditLog.action, 'audit.checkpoint')))
+    .orderBy(desc(auditLog.seq))
+    .limit(1);
+  return row === undefined ? undefined : stored([row])[0];
+}
+
+/**
+ * The vault's checkpoints that keep a tally after entry `after` and through
+ * `through`, oldest first, whole: as many as `BATCH_BYTES` of what they say
+ * holds, but always one. A reader asks again after the last.
+ */
+export async function talliedWithin(db: Queryable, after: bigint, through: bigint, limit: number): Promise<StoredEntry[]> {
+  const { auditLog } = tablesOf(db);
+  const tallied = and(
+    eq(auditLog.author, 'vault'), eq(auditLog.action, 'audit.checkpoint'), eq(auditLog.decision, 'allow'), isNotNull(auditLog.relatedSeq),
+    gt(auditLog.seq, after), lte(auditLog.seq, through),
+  );
+  const batch = await withinBytes(db, tallied, limit);
+  if (batch === null) return [];
+  const rows = await db.select(entryColumns(db)).from(auditLog)
+    .where(and(tallied, gte(auditLog.seq, batch.from), lte(auditLog.seq, batch.to))).orderBy(asc(auditLog.seq));
+  return stored(rows);
+}
+
+/** The vault's newest refusal of `action` with `code` after entry `after`, or undefined: one range of the (author, action, seq) index. */
+export async function newestRefusal(db: Queryable, action: string, code: string, after: bigint): Promise<StoredEntry | undefined> {
+  const { auditLog } = tablesOf(db);
+  const [row] = await db
+    .select(entryColumns(db))
+    .from(auditLog)
+    .where(and(eq(auditLog.author, 'vault'), eq(auditLog.action, action), gt(auditLog.seq, after), eq(auditLog.decision, 'deny'), eq(auditLog.code, code)))
+    .orderBy(desc(auditLog.seq))
+    .limit(1);
+  return row === undefined ? undefined : stored([row])[0];
+}
+
+/** Up to `limit` of the vault's checkpoints that keep a tally after entry `after`, oldest first: each one's entry, and the last entry it signs. */
+export async function talliedAfter(db: Queryable, after: bigint, limit: number): Promise<{ seq: bigint; signs: bigint }[]> {
+  const { auditLog } = tablesOf(db);
+  const rows = await db
+    .select({ seq: auditLog.seq, signs: auditLog.relatedSeq })
+    .from(auditLog)
+    .where(and(
+      eq(auditLog.author, 'vault'),
+      eq(auditLog.action, 'audit.checkpoint'),
+      eq(auditLog.decision, 'allow'),
+      isNotNull(auditLog.relatedSeq),
+      gt(auditLog.seq, after),
+    ))
+    .orderBy(asc(auditLog.seq))
+    .limit(limit);
+  return rows.map(({ seq, signs }) => ({ seq, signs: signs! }));
+}
+
 /** The vault's newest allowed access entry about each member who has one. */
 export async function newestAccessEntries(db: Queryable): Promise<Map<string, StoredEntry>> {
   const { auditLog } = tablesOf(db);

package/src/tally.ts

@@ -0,0 +1,241 @@
+import { createHash } from 'node:crypto';
+
+import type { StoredEntry } from '@coffre/core/audit';
+import type { AccessFault, Checkpoint, LogHead } from '@coffre/core/vault';
+
+import { KeyAccounting, type AccountingState } from './accounting.ts';
+import { forward } from './log.ts';
+import { apply, placeKey, type LoggedMember, type Replayed } from './replay.ts';
+import { ACCESS_ACTIONS, type GrantRow } from './store.ts';
+
+/**
+ * What a walk of the vault's entries from the first has gathered by some
+ * entry: all a walk from there needs to go on as if it had started at the
+ * first. A checkpoint keeps the tally of the prefix it signs, so that the
+ * next checkpoint, and every verification, start from it and read only the
+ * entries since (docs/architecture.md, "The tally").
+ *
+ * - `entries`: the vault's entries so far;
+ * - `keys`: the vault's log keys, in the order its entries moved through
+ *   them, which only moves forward (`forward` in log.ts);
+ * - `accounting`: the key batches still under way, and the first fault in
+ *   their entries;
+ * - `access`: who the log says is a member, what each holds, and each one's
+ *   newest access entry, which their row must name;
+ * - `replayFault`: the first access entry about someone never admitted.
+ *
+ * The faults are kept, once found, as a walk from the first entry would
+ * find them again each time.
+ */
+export type Tally = {
+  entries: number;
+  keys: string[];
+  accounting: AccountingState;
+  access: AccessTally;
+  replayFault: AccessFault | null;
+};
+
+/** Members and grants as the log says they are, and each member's newest access entry, as plain JSON. */
+export type AccessTally = {
+  members: (Omit<LoggedMember, 'accessSeq'> & { accessSeq: number })[];
+  grants: GrantRow[];
+  newest: [principal: string, seq: number][];
+};
+
+/**
+ * A tally as a checkpoint's entry holds it. Members and grants change far
+ * less often than every five minutes, so `access` is written whole only
+ * when it changed since the tally resumed from; otherwise the entry names
+ * the checkpoint entry that holds it (`at`). Either way with its digest.
+ */
+export type StoredTally = Omit<Tally, 'access'> & { v: typeof TALLY_VERSION; access: { digest: string } & ({ at: number } | AccessTally) };
+
+/**
+ * What a tally keeps, as 0.10.1 wrote it. A release that keeps more, or
+ * less, writes another version, and compares a tally of this one on what
+ * this one kept: a walk from the first entry passes every tally ever
+ * written, and an honest one must still match. A release rolled back to
+ * reads no tally newer than its own, and refuses the checkpoints that
+ * keep one: going back across a version is not a way back.
+ */
+export const TALLY_VERSION = 1;
+
+/**
+ * A checkpoint as the vault's entry holds it: the signed prefix, its
+ * tally, and the lap of the rehash of the past under way (`scrub`): the
+ * prefix it rehashes to, signed when the lap began, and the last entry it
+ * rehashed. Null between laps.
+ */
+export type TalliedCheckpoint = Checkpoint & { tally: StoredTally; scrub: { at: LogHead; end: LogHead } | null };
+
+/** Before the first entry. */
+export const EMPTY_TALLY: Tally = {
+  entries: 0,
+  keys: [],
+  accounting: { intents: [], fault: null },
+  access: { members: [], grants: [], newest: [] },
+  replayFault: null,
+};
+
+/** The digest of what `access` says, over its canonical form. */
+export function accessDigest(access: AccessTally): string {
+  return createHash('sha256').update(canonical(access)).digest('hex');
+}
+
+/**
+ * What two tallies are compared by, so that they match whatever order
+ * their maps were built in: the members and grants by their digest, which
+ * a stretch passing many checkpoints computes once a change; and a fault by
+ * where it was found, since the words for it may change from one release
+ * to the next.
+ */
+function tallyKey({ accounting, entries, keys, replayFault }: Omit<Tally, 'access'>, digest: string): string {
+  return canonical({ entries, keys, replayFault, accounting: { ...accounting, fault: accounting.fault?.failedAtSeq ?? null }, access: digest });
+}
+
+/**
+ * A tally a walk must come to: the one a checkpoint keeps, `entry`, of the
+ * prefix through `through`; or why that checkpoint's tally cannot be read.
+ */
+export type Expected = { entry: bigint; through: bigint; key: string } | { entry: bigint; through: bigint; unreadable: string };
+
+/**
+ * What a walk must come to at a checkpoint, from the tally it keeps: its
+ * members and grants by the digest it keeps of them, never read.
+ */
+export function expectedKey(stored: StoredTally): string {
+  return tallyKey(stored, stored.access.digest);
+}
+
+/**
+ * The vault's entries walked, oldest first, each after its MAC was checked,
+ * gathered into what the checks after the walk need: the tally it started
+ * from, carried on.
+ */
+export class Walk {
+  readonly accounting: KeyAccounting;
+  readonly replayed: Replayed;
+  /** Each member's newest allowed access entry, by seq. */
+  readonly newestAccess: Map<string, bigint>;
+  /** The first access entry the replay could not apply. */
+  replayFault: AccessFault | null;
+  /** The vault's entries so far, those before the walk included. */
+  entries: number;
+  /** The vault's log keys, as the log moved through them. */
+  keys: readonly string[];
+  /** The checkpoints walked, each to be checked against its signature and the prefix it signed once the walk ends: what it signed, and nothing it keeps beside. */
+  readonly checkpoints: { entry: { seq: bigint; keyId: string; relatedSeq: bigint | null }; checkpoint: Checkpoint }[] = [];
+
+  /** The tallies the walk must come to as it passes them, oldest first (`expect`). */
+  #expected: Expected[] = [];
+  /** The first it did not come to, and why. */
+  mismatch: { entry: bigint; reason: string } | null = null;
+  /** The digest of the members and grants as the walk has them, until an access entry changes them. */
+  #digest: string | null = null;
+
+  /** The digest of the members and grants as the walk has them: the tally's it started from, until an access entry. */
+  digest(): string {
+    return (this.#digest ??= accessDigest(this.tally().access));
+  }
+
+  /** The tally but for its members and grants, which `digest` stands for. */
+  #unaccessed(): Omit<Tally, 'access'> {
+    return { entries: this.entries, keys: [...this.keys], accounting: this.accounting.state(), replayFault: this.replayFault };
+  }
+
+  /** `digest` is that of `from`'s members and grants, when the caller has it: a beat with no access entry hashes none. */
+  constructor(from: Tally, digest?: string) {
+    this.#digest = digest ?? null;
+    this.accounting = new KeyAccounting(from.accounting);
+    this.replayed = {
+      members: new Map(from.access.members.map((member) => [member.principal, { ...member, accessSeq: BigInt(member.accessSeq) }])),
+      held: new Map(),
+    };
+    for (const grant of from.access.grants) {
+      const held = this.replayed.held.get(grant.principal) ?? new Map<string, GrantRow>();
+      this.replayed.held.set(grant.principal, held);
+      held.set(placeKey(grant), { ...grant });
+    }
+    this.newestAccess = new Map(from.access.newest.map(([principal, seq]) => [principal, BigInt(seq)]));
+    this.replayFault = from.replayFault;
+    this.entries = from.entries;
+    this.keys = from.keys;
+  }
+
+  /**
+   * Hold the walk to these tallies, each as the walk stands once it has
+   * read every entry through the prefix's end: before the vault's next
+   * entry, since only the vault's change a tally, or at `finish`.
+   */
+  expect(expected: readonly Expected[]): void {
+    this.#expected = [...expected].sort((a, b) => (a.through < b.through ? -1 : 1));
+  }
+
+  /** The tallies expected through `through`, held to the walk. */
+  finish(through: bigint): void {
+    this.#reach(through + 1n);
+  }
+
+  #reach(before: bigint): void {
+    while (this.#expected.length > 0 && this.#expected[0]!.through < before) {
+      const expected = this.#expected.shift()!;
+      if (this.mismatch !== null) continue;
+      if ('unreadable' in expected) this.mismatch = { entry: expected.entry, reason: expected.unreadable };
+      else if (tallyKey(this.#unaccessed(), this.digest()) !== expected.key) {
+        this.mismatch = { entry: expected.entry, reason: 'the tally this checkpoint keeps does not follow from the log before it' };
+      }
+    }
+  }
+
+  /**
+   * One of the vault's entries, its MAC checked, in the log's order: a
+   * fault when it is under a key the vault had moved past (`forward`).
+   */
+  add(entry: StoredEntry, current: string): { failedAtSeq: bigint; reason: string } | null {
+    this.#reach(entry.seq);
+    const moved = forward([entry], this.keys, current);
+    if ('failedAtSeq' in moved) return moved;
+    this.keys = moved.keys;
+    this.entries += 1;
+    this.accounting.add(entry);
+    if (entry.decision !== 'allow') return null;
+    if (ACCESS.has(entry.action)) {
+      this.#digest = null;
+      this.replayFault ??= apply(this.replayed, entry);
+      if (entry.subjectPrincipal !== null) this.newestAccess.set(entry.subjectPrincipal, entry.seq);
+    } else if (entry.action === CHECKPOINT) {
+      const { seq, hash, signedAt, keyId, signature } = JSON.parse(entry.metadata) as Checkpoint;
+      this.checkpoints.push({ entry: { seq: entry.seq, keyId: entry.keyId, relatedSeq: entry.relatedSeq }, checkpoint: { seq, hash, signedAt, keyId, signature } });
+    }
+    return null;
+  }
+
+  /** Where the walk stands, to resume from. */
+  tally(): Tally {
+    const byPrincipal = <T>(entries: Iterable<[string, T]>) => [...entries].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return {
+      entries: this.entries,
+      keys: [...this.keys],
+      accounting: this.accounting.state(),
+      access: {
+        members: byPrincipal(this.replayed.members).map(([, member]) => ({ ...member, accessSeq: Number(member.accessSeq) })),
+        grants: byPrincipal(this.replayed.held).flatMap(([, held]) => byPrincipal(held).map(([, grant]) => grant)),
+        newest: byPrincipal(this.newestAccess).map(([principal, seq]) => [principal, Number(seq)]),
+      },
+      replayFault: this.replayFault,
+    };
+  }
+}
+
+/** The action of the vault's entry that signs a prefix of the log. */
+export const CHECKPOINT = 'audit.checkpoint';
+
+const ACCESS = new Set<string>(ACCESS_ACTIONS);
+
+/** JSON with every object's keys sorted: one text for one value, however it was built. */
+function canonical(value: unknown): string {
+  return JSON.stringify(value, (_, inner: unknown) =>
+    inner !== null && typeof inner === 'object' && !Array.isArray(inner)
+      ? Object.fromEntries(Object.entries(inner).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+      : inner);
+}