@coffre/vault 0.14.4 → 0.15.0

package/src/retention.ts

@@ -0,0 +1,229 @@
+import { leafData, openPair, proveConsistency, TREES, verifyConsistency, type Cut, type LogEntry, type StoredPair } from '@coffre/core/merkle';
+
+import { FenceClosed, type Checkpointer, type CheckpointStore } from './checkpointer.ts';
+import { entryMac, RETENTION_ACTOR, RETENTION_OBJECT, retentionCut, retentionPayload, type LogMacKey } from './log-entry.ts';
+import { cursorHolds, type ReadsCursor } from './reads.ts';
+
+/**
+ * Retention (docs/design/0.15-plan.md, PR 7; formal/Seal.tla's retention):
+ * days of uses dropped once a sealed retention change cuts the uses tree
+ * above them, and the uses tree's tiles below the cut, the one holding it at
+ * each level kept. Changes are kept for good: the changes tree is never cut.
+ *
+ * A day goes in these steps, oldest first, each a precondition of the next:
+ * 1. Its cut: the first pair whose floor of `at` is past the day's end. Every
+ *    use of the day took its number at or below it (a use's `at` is held to
+ *    the floor), so all of them lie below the cut; a few of the next day's
+ *    do too (stragglers), and stay until their own day goes. The cut must be
+ *    a pair the signer signed, the first past the day's end by its own note
+ *    (its `prev`, the floor of the pair signed before it, below the end:
+ *    CutFirst), on its history (a consistency proof to its head in both
+ *    trees), at or below its head.
+ * 2. The retention change naming it, unless the newest sealed one already
+ *    cuts at or past it (a quiet day, or a retry): appended, and sealed in
+ *    the signer's pair (DropAfterSeal; else the verifier, walking the uses
+ *    from genesis, would find the day gone).
+ * 3. Freshness: the pair that sealed it (or the signer's, for a day an older
+ *    change cuts) at least two freshness bounds past the cut (FreshBeforeDrop).
+ *    The signer refuses any entry stamped a bound before its pair (FRESH_MS),
+ *    so no copy of a dropped use, which keeps its stamp and has no original
+ *    left for a request-ID check to find, is ever sealed again. Two bounds,
+ *    not one: one for the clocks.
+ * 4. The day's partition: detached, and dropped by the next run (`drop_day`).
+ *    Measured at 1,000 uses a second (0.15-plan.md, "As built: PR 7"): a DROP
+ *    right after the DETACH lands while every backend replans its plan of
+ *    `log_uses`, and stalls uses 200 to 400 ms; seconds later, it stalls none.
+ *    A crash between any two steps is finished by the next run.
+ * Then the tiles below the newest cut (`drop_tiles`).
+ *
+ * The signer's checks are the vault's: its memory, its pair, its keys. The
+ * database's functions check what they can see, so that the vault's login
+ * drops nothing a retention change it holds does not cut.
+ */
+export type RetentionStore = {
+  /** How far the reads' projector has gone (reads.ts, T166), with its MAC: no day nor tile it has yet to read is dropped. */
+  readsCursor(): Promise<ReadsCursor>;
+  /** The UTC days of uses the database holds, oldest first: YYYY-MM-DD. */
+  days(): Promise<string[]>;
+  /** Makes each day's partition of uses (`make_day`), once a store. */
+  makeDays(days: readonly string[]): Promise<void>;
+  /** The first checkpoint whose floor of `at` is at or past `ms`. */
+  cutAt(ms: number): Promise<StoredPair | null>;
+  /** The newest retention change at or below the newest checkpoint, with its leaf index; null if none. */
+  retention(): Promise<{ entry: LogEntry; index: number } | null>;
+  /** Appends a retention change, or finds the one its request ID names: its number. */
+  appendRetention(change: { requestId: string; at: number; payload: string; mac: Buffer }): Promise<bigint>;
+  /** One step of dropping a day: detached, dropped, or gone. */
+  dropDay(day: string): Promise<'detached' | 'dropped' | 'gone'>;
+  /** The uses tree's tiles wholly below leaf `below`: how many were deleted or ranges dropped. */
+  dropTiles(below: number): Promise<number>;
+  /** At most `limit` of the bulk cap's rows that its window no longer counts: how many went. */
+  pruneBulk(limit: number): Promise<number>;
+};
+
+export const DAY_MS = 86_400_000;
+
+/** A UTC day, YYYY-MM-DD, of a time in ms. */
+export const dayOf = (ms: number) => new Date(ms).toISOString().slice(0, 10);
+
+export type RetentionRun = {
+  /** The days whose uses went this run, each with the retention change written for it, if one was. */
+  dropped: { day: string; change: bigint | null }[];
+  /** Of those, the days detached and not dropped yet: the next run drops them. */
+  detached: string[];
+  /**
+   * Why the run stopped before a due day (`day`) or the tiles (no day), when it waits for something: the log to move on,
+   * or (`lock`) a reader holding the uses past the lock timeout. No alarm; a lock standing a day is one (`upkeep`).
+   */
+  waiting: { day: string | null; lock: boolean; reason: string } | null;
+  /** Tiles deleted or leaf ranges dropped below the newest cut. */
+  tiles: number;
+};
+
+type Options = {
+  /** Full days of uses kept before today's: a day goes once `keepDays` days have ended after it. */
+  keepDays: number;
+  /** The log's MAC key (`logMacKey`): the retention change is an entry like any. */
+  macKey: LogMacKey;
+  now?: () => number;
+};
+
+/**
+ * One run. Throws on what is an alarm (a cut off the signer's history, a
+ * retention change not sealed, a day the database refuses); returns `waiting`
+ * when a day is not ready yet.
+ */
+export async function retain(cp: Checkpointer, store: CheckpointStore & RetentionStore, options: Options): Promise<RetentionRun> {
+  if (!Number.isSafeInteger(options.keepDays) || options.keepDays < 1) throw new Error(`keepDays must be a whole number of days, at least 1, not ${options.keepDays}`);
+  const now = options.now ?? Date.now;
+  const run: RetentionRun = { dropped: [], detached: [], waiting: null, tiles: 0 };
+  const last = dayOf(now() - (options.keepDays + 1) * DAY_MS);
+  for (const day of (await store.days()).filter((d) => d <= last)) {
+    const done = await retainDay(cp, store, day, options.macKey, now);
+    if ('reason' in done) {
+      run.waiting = { day, ...done };
+      break;
+    }
+    run.dropped.push({ day, change: done.change });
+    // One DETACH a run: each invalidates every backend's plan of log_uses, and a second landing while they replan stalls
+    // uses (measured for a DROP: 0.15-plan.md, "As built: PR 7"). A backlog of days goes a day an hour.
+    if (done.detached) {
+      run.detached.push(day);
+      break;
+    }
+  }
+  // The tiles below the newest cut, once its sealing is two freshness bounds past it, as a day goes (FreshBeforeDrop).
+  const newest = await sealedCut(cp, store);
+  const projecting = newest === null ? null : await behindReads(store, options.macKey, newest.upto);
+  if (projecting !== null) run.waiting ??= { day: null, lock: false, reason: `the tiles below ${newest!.upto}: ${projecting}` };
+  else if (newest !== null && cp.pair.pair.at >= newest.at + 2 * cp.freshMs) {
+    const tiles = await waitingOnLock(() => store.dropTiles(newest.uses.size));
+    if (typeof tiles === 'number') run.tiles = tiles;
+    else run.waiting ??= { day: null, lock: true, reason: `the tiles below ${newest.upto}: ${tiles.reason}` };
+  }
+  return run;
+}
+
+/** One day: dropped, with the change written for it if any; or why it waits. */
+type Wait = { lock: boolean; reason: string };
+
+async function retainDay(cp: Checkpointer, store: CheckpointStore & RetentionStore, day: string, macKey: LogMacKey, now: () => number): Promise<{ change: bigint | null; detached: boolean } | Wait> {
+  const end = Date.parse(`${day}T00:00:00Z`) + DAY_MS;
+  const head = cp.pair.pair;
+  if (head.floor < end) return { lock: false, reason: `the signer's newest pair (up to ${head.upto}) is not past the day's end yet` };
+  // 1. The cut: a pair of this log at or below the signer's, the first it signed past the day's end by its own note (its
+  // floor at or past the end, the floor before it below: CutFirst). The rows say which pair that is, and a writer who
+  // deletes some, or edits their floors, would make a later one pass for it, and every use between go unwalked.
+  const row = await store.cutAt(end);
+  const cut = row === null ? null : await openPair(row.notes, cp.verifiers);
+  if (row === null || cut === null || cut.upto !== row.upto || cut.floor < end || cut.prev >= end || cut.upto > head.upto) {
+    throw new Error(`retention of ${day}: the database holds no pair of this log, at or below the signer's (up to ${head.upto}), that is the first past the day's end: checkpoints were deleted or replaced`);
+  }
+  // On the signer's history, by a consistency proof to its head; unless the newest sealed cut is at or past it (a day a
+  // change already cut, or one waiting to be dropped): that cut was proved when it was sealed, and the tiles below it,
+  // which a proof from this one would read, may be gone.
+  const sealed = await sealedCut(cp, store);
+  if (sealed === null || sealed.upto < cut.upto) {
+    for (const tree of TREES) {
+      if (cut[tree].size === head[tree].size && cut.upto === head.upto) continue;
+      // A fence closed under it (T169) is no answer of the database's: it goes through, and no alarm says the cut is off.
+      const proof = cut[tree].size > head[tree].size ? null : await proveConsistency(store, tree, cut[tree].size, head[tree].size).catch((error: unknown) => {
+        if (error instanceof FenceClosed) throw error;
+        return null;
+      });
+      if (proof === null || !verifyConsistency(cut[tree].size, head[tree].size, cut[tree].root, head[tree].root, proof)) {
+        throw new Error(`retention of ${day}: the cut's ${tree} head (up to ${cut.upto}) is not on the signer's history`);
+      }
+    }
+  }
+  // 2. The retention change, unless the newest sealed one cuts at or past this day's.
+  let change: bigint | null = null;
+  let freshAt = head.at;
+  if (sealed === null || sealed.upto < cut.upto) {
+    const named: Cut = { upto: cut.upto, at: cut.at, uses: { size: cut.uses.size, root: cut.uses.root } };
+    const at = now();
+    const requestId = `retention:${day}`;
+    const payload = retentionPayload(day, named);
+    const mac = entryMac(macKey, { tree: 'changes', row: { at, requestId, object: RETENTION_OBJECT, actor: RETENTION_ACTOR, payload, seal: null } });
+    change = await store.appendRetention({ requestId, at, payload, mac });
+    // Sealed in the signer's pair, witnessed or not: its proof is checked against the pair. A retry finds the change it
+    // made before, whose cut is this day's (the first pair past its end) unless the rows moved: then nothing is dropped.
+    const answer = await cp.sealThrough(change);
+    const entry = (await store.retention())?.entry;
+    const written = entry?.number === change ? retentionCut(entry) : null;
+    if (written === null || written.upto !== cut.upto || !leafData('changes', entry!.number, entry!.columns).equals(answer.proof.leaf)) {
+      throw new Error(`retention of ${day}: the retention change ${change} is not the one sealed, or does not cut at ${cut.upto}`);
+    }
+    freshAt = answer.pair.at;
+  }
+  // 3. Freshness, against the signer's own pair, never a row.
+  const bound = Math.max(cut.at, end) + 2 * cp.freshMs;
+  if (freshAt < bound) return { lock: false, reason: `the pair sealing its cut (at ${freshAt}) is not two freshness bounds past it (${bound}) yet` };
+  // 4. Not before the reads' projector has read every use at or below the cut (T166): those it has yet to list would
+  // otherwise never be, and the range it walks needs the tiles too.
+  const projecting = await behindReads(store, macKey, cut.upto);
+  if (projecting !== null) return { lock: false, reason: projecting };
+  // 5. The day's partition: detached now, and dropped by a later run, never right after its DETACH (see above). A reader
+  // holding log_uses longer than `drop_day`'s lock_timeout (a backup, say) makes it give up: the next run tries again.
+  let state = await waitingOnLock(() => store.dropDay(day));
+  if (state === 'dropped') state = await waitingOnLock(() => store.dropDay(day));
+  if (typeof state === 'object') return state;
+  if (state === 'dropped') throw new Error(`retention of ${day}: its uses were not dropped`);
+  return { change, detached: state === 'detached' };
+}
+
+/**
+ * Why a cut waits on the reads' projector (T166), or null once it has gone
+ * past it: by the cursor the vault's MAC holds, never a number a database
+ * writer moved on, which would drop uses the projector has yet to list
+ * (review r7). Such a cursor stops the projector too, so retention waits,
+ * and alarms once it has waited long.
+ */
+async function behindReads(store: RetentionStore, macKey: LogMacKey, upto: bigint): Promise<string | null> {
+  const cursor = await store.readsCursor();
+  if (!cursorHolds(macKey, cursor)) return `the reads' cursor, at ${cursor.through}, is not the vault's: it was moved around the projector`;
+  return cursor.through >= upto ? null : `the reads' projection (through ${cursor.through}) has not reached the cut (${upto}) yet`;
+}
+
+/** What `work` answers, or, when the database gave up waiting for a lock (55P03, lock_timeout), why: no alarm. */
+async function waitingOnLock<T>(work: () => Promise<T>): Promise<T | Wait> {
+  try {
+    return await work();
+  } catch (error) {
+    const e = error as { code?: unknown; cause?: { code?: unknown } };
+    if (e.code === '55P03' || e.cause?.code === '55P03') return { lock: true, reason: 'a reader holds the table past the lock timeout: the next run tries again' };
+    throw error;
+  }
+}
+
+/** The newest retention change's cut, proved in the signer's pair; null if there is none. */
+async function sealedCut(cp: Checkpointer, store: RetentionStore): Promise<Cut | null> {
+  const found = await store.retention();
+  if (found === null) return null;
+  const cut = retentionCut(found.entry);
+  const proof = await cp.prove(found.entry.number, { tree: 'changes' });
+  if (cut === null || proof === null || proof.tree !== 'changes' || !proof.leaf.equals(leafData('changes', found.entry.number, found.entry.columns))) {
+    throw new Error(`the retention change ${found.entry.number} is not sealed in the signer's changes tree as the database holds it`);
+  }
+  return cut;
+}

package/src/snapshot.postgres.ts

@@ -22,6 +22,19 @@ export function snapshotQuery(asked: Asked): SQL {
   const actions = sql`${sql.param([...ACCESS_ACTIONS])}::text[]`;
   const tomb = `%${TOMBSTONE}%`;
   const released = asked.released;
+  const seals = asked.seals === true;
+  // The places read: those asked, the environments each personal config among them is a config of, with `seals` those
+  // the asked principals' grants are on (whose projects their grants are read with), and what the newest policy
+  // protects, by the ids its JSON names (one that is no UUID names nothing).
+  const placeIds = sql`ARRAY(
+          SELECT unnest(${environments})
+          UNION SELECT parent_id FROM environments WHERE id = ANY(${environments}) AND owner IS NOT NULL${asked.seals === true
+            ? sql`
+          UNION SELECT environment_id FROM vault_grants WHERE principal = ANY(${principals}) AND environment_id IS NOT NULL`
+            : sql``}
+          UNION SELECT (place #>> '{}')::uuid FROM policy, jsonb_path_query(policy.metadata::jsonb, '$.policy.protected[*].environmentId') AS place
+          WHERE (place #>> '{}') ~* '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
+        )`;
   // The head only if nobody holds it: a statement never waits for it, so all it reads is as of when it took it (`snapshot`).
   const head = asked.head === true
     ? sql`, head AS (SELECT next_seq, head_hash FROM audit_chain_head WHERE only_row FOR UPDATE SKIP LOCKED)`
@@ -60,21 +73,38 @@ export function snapshotQuery(asked: Asked): SQL {
         ) e
       ),
       'policy', (SELECT ${ENTRY} FROM policy e),
+      'settings', ${asked.settings === true
+        ? sql`(SELECT ${ENTRY} FROM audit_log e WHERE author = 'vault' AND action = 'settings.change' AND decision = 'allow' ORDER BY seq DESC LIMIT 1)`
+        : sql`NULL`},
       'environments', (
         SELECT coalesce(json_agg(json_build_object(
           'id', env.id, 'projectId', env.project_id, 'slug', env.slug, 'owner', env.owner, 'parentId', env.parent_id,
           'deleted', env.slug LIKE ${tomb} OR project.slug LIKE ${tomb},
-          'archived', env.archived_at IS NOT NULL OR project.archived_at IS NOT NULL)), '[]')
+          'archived', env.archived_at IS NOT NULL OR project.archived_at IS NOT NULL${seals
+            ? sql`,
+          -- What 0.15's log holds the row to (T159): its object's own columns, its seal, and its newest change's, one probe
+          -- of its object's changes, newest first (log_changes_object_idx, which holds the seal).
+          'protected', env.protected, 'ownArchived', env.archived_at IS NOT NULL, 'projectArchived', project.archived_at IS NOT NULL,
+          'seal', encode(env.seal, 'hex'),
+          'newest', (SELECT encode(l.seal, 'hex') FROM log_changes l WHERE l.object = log_object('environment', env.id::text) ORDER BY l.number DESC LIMIT 1)`
+            : sql``})), '[]')
         FROM environments env JOIN projects project ON project.id = env.project_id
         -- One list of ids, each found by the primary key.
-        WHERE env.id = ANY(ARRAY(
-          SELECT unnest(${environments})
-          UNION SELECT parent_id FROM environments WHERE id = ANY(${environments}) AND owner IS NOT NULL
-          -- What the newest policy protects, by the ids its JSON names; one that is no UUID names nothing.
-          UNION SELECT (place #>> '{}')::uuid FROM policy, jsonb_path_query(policy.metadata::jsonb, '$.policy.protected[*].environmentId') AS place
-          WHERE (place #>> '{}') ~* '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
-        ))
-      ),
+        WHERE env.id = ANY(${placeIds})
+      ),${seals
+        ? sql`
+      -- Of those ids, each the log holds a change of but no row (or no project's) answers to: deleted outright around it,
+      -- with its newest change's seal (T159, review r5). One probe of its object's changes each.
+      'gone', (
+        SELECT coalesce(json_agg(json_build_object('id', g.id, 'newest', encode(l.seal, 'hex'))), '[]')
+        FROM (
+          SELECT a.id FROM unnest(${placeIds}) AS a (id)
+          WHERE NOT EXISTS (SELECT 1 FROM environments env JOIN projects project ON project.id = env.project_id WHERE env.id = a.id)
+          OFFSET 0
+        ) g
+        CROSS JOIN LATERAL (SELECT l.seal FROM log_changes l WHERE l.object = log_object('environment', g.id::text) ORDER BY l.number DESC LIMIT 1) l
+      ),`
+        : sql``}
       'ended', (
         SELECT coalesce(json_agg(related_seq::text), '[]') FROM audit_log
         WHERE author = 'vault' AND action = 'reference.end' AND decision = 'allow' AND related_seq = ANY(${references})

package/src/snapshot.sqlite.ts

@@ -31,6 +31,7 @@ export function snapshotQuery(asked: Asked): SQL {
   const tomb = `%${TOMBSTONE}%`;
   const released = asked.released;
   const head = asked.head === true;
+  const seals = asked.seals === true;
   return sql`
     WITH policy AS (
       SELECT * FROM audit_log WHERE author = 'vault' AND action = 'policy.change' AND decision = 'allow' ORDER BY seq DESC LIMIT 1
@@ -66,21 +67,45 @@ export function snapshotQuery(asked: Asked): SQL {
         ) WHERE newest IS NOT NULL
       )),
       'policy', json((SELECT ${ENTRY} FROM policy e)),
+      'settings', ${asked.settings === true
+        ? sql`json((SELECT ${ENTRY} FROM audit_log e WHERE author = 'vault' AND action = 'settings.change' AND decision = 'allow' ORDER BY seq DESC LIMIT 1))`
+        : sql`NULL`},
       'environments', json((
         SELECT json_group_array(json_object(
           'id', env.id, 'projectId', env.project_id, 'slug', env.slug, 'owner', env.owner, 'parentId', env.parent_id,
           'deleted', env.slug LIKE ${tomb} OR project.slug LIKE ${tomb},
-          'archived', env.archived_at IS NOT NULL OR project.archived_at IS NOT NULL))
+          'archived', env.archived_at IS NOT NULL OR project.archived_at IS NOT NULL${seals
+            ? sql`,
+          -- What 0.15's log holds the row to (T159), but its newest change's seal, which snapshot reads after.
+          'protected', env.protected, 'ownArchived', env.archived_at IS NOT NULL, 'projectArchived', project.archived_at IS NOT NULL,
+          'seal', lower(hex(env.seal))`
+            : sql``}))
         FROM environments env JOIN projects project ON project.id = env.project_id
         WHERE env.id IN (SELECT value FROM json_each(${environments}))
-          OR env.id IN (SELECT parent_id FROM environments WHERE id IN (SELECT value FROM json_each(${environments})) AND owner IS NOT NULL)
+          OR env.id IN (SELECT parent_id FROM environments WHERE id IN (SELECT value FROM json_each(${environments})) AND owner IS NOT NULL)${seals
+            ? sql`
+          OR env.id IN (SELECT environment_id FROM vault_grants WHERE principal IN (SELECT value FROM json_each(${principals})) AND environment_id IS NOT NULL)`
+            : sql``}
           OR env.id IN (
             SELECT json_extract(place.value, '$.environmentId')
             FROM policy, json_each(policy.metadata, '$.policy.protected') AS place
             -- Of a forged entry's, an element that is no object names nothing: json_extract would fail on a string.
             WHERE json_valid(policy.metadata) AND json_type(policy.metadata, '$.policy.protected') = 'array' AND place.type = 'object'
           )
-      )),
+      )),${seals
+        ? sql`
+      -- Every place id asked, row or none: snapshot finds those the log holds a change of and no row answers to (review r5).
+      'placeIds', json((
+        SELECT json_group_array(id) FROM (
+          SELECT value AS id FROM json_each(${environments})
+          UNION SELECT parent_id FROM environments WHERE id IN (SELECT value FROM json_each(${environments})) AND owner IS NOT NULL
+          UNION SELECT environment_id FROM vault_grants WHERE principal IN (SELECT value FROM json_each(${principals})) AND environment_id IS NOT NULL
+          UNION SELECT json_extract(place.value, '$.environmentId')
+            FROM policy, json_each(policy.metadata, '$.policy.protected') AS place
+            WHERE json_valid(policy.metadata) AND json_type(policy.metadata, '$.policy.protected') = 'array' AND place.type = 'object'
+        ) WHERE id IS NOT NULL
+      )),`
+        : sql``}
       'ended', json((
         SELECT json_group_array(related_seq) FROM audit_log
         WHERE author = 'vault' AND action = 'reference.end' AND decision = 'allow' AND related_seq IN (SELECT value FROM json_each(${references}))

package/src/snapshot.ts

@@ -1,11 +1,12 @@
 import type { StoredEntry } from '@coffre/core/audit';
 import type { Queryable, Transaction } from '@coffre/db';
-import { LogHeadMismatch, lockLogHead } from '@coffre/db/log';
+import { LogHeadMismatch, lockLogHead, lockLogHeadQueued } 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 { objectKey } from './inputs.ts';
 import * as store from './store.ts';
 import type { EnvironmentRow, Member } from './store.ts';
 
@@ -39,9 +40,13 @@ export type Snapshot = {
   newestAccess: Map<string, StoredEntry>;
   /** The newest allowed `policy.change` in the vault's name, unchecked. */
   newestPolicy: StoredEntry | null;
+  /** With `asked.settings`, the newest allowed `settings.change` in the vault's name, unchecked, or null for none; not asked, undefined. */
+  newestSettings: StoredEntry | null | undefined;
   /**
    * The asked environments, the environments each personal config among
-   * them is a config of, and those the newest `policy.change` names, by id.
+   * them is a config of, and those the newest `policy.change` names, by id;
+   * with `asked.seals`, those the asked principals' grants are on too, each
+   * with what 0.15's log holds it to (`EnvironmentRow.sealed`).
    */
   environments: Map<string, EnvironmentRow>;
   /** Of the asked `reference.create` entries, those a `reference.end` of the vault's names, allowed. */
@@ -72,7 +77,15 @@ export type Asked = {
   /** Whose grants and newest access entry; with `members`, their rows too, unlocked. */
   principals: readonly string[];
   members?: boolean;
+  /** The newest `settings.change` too (`newestSettings`). */
+  settings?: boolean;
   environments?: readonly string[];
+  /**
+   * Each environment read with what 0.15's log holds it to, and the asked
+   * principals' grants' too, whose projects their grants are read with
+   * (T159): asked once 0.15's log is cut over, before which no row is sealed.
+   */
+  seals?: boolean;
   references?: readonly bigint[];
   /**
    * One principal's releases within the last `windowMs` of the clock, moved
@@ -83,6 +96,12 @@ export type Asked = {
   released?: { principal: string; keys: readonly string[]; windowMs: number; clockOffsetMs: number; cap: number };
   /** Lock the log's head first. */
   head?: boolean;
+  /**
+   * Held by another, wait for the head only in one of this many places in
+   * line, and refuse at once when none is free (`lockLogHeadQueued`); with
+   * none, wait as long as the transaction's bound lets.
+   */
+  waiters?: number;
 };
 
 /** One statement's read, as `Snapshot` says; with the head, two more when another holds it. */
@@ -94,7 +113,7 @@ export async function snapshot(db: Queryable, asked: Asked): Promise<Snapshot> {
   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);
+  if (first.head === null) await (asked.waiters === undefined ? lockLogHead(db as Transaction) : lockLogHeadQueued(db as Transaction, asked.waiters));
   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`).
@@ -111,20 +130,48 @@ export function current(head: LockedHead): boolean {
 }
 
 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;
+  const engine = engineOf(db);
+  const query = (engine === 'postgres' ? postgres : sqlite)(asked);
+  const statement = async (on: Queryable) => {
+    const [row] = await rowsOf<{ snapshot: string | Raw }>(on, query);
+    return typeof row!.snapshot === 'string' ? (JSON.parse(row!.snapshot) as Raw) : row!.snapshot;
+  };
+  if (engine === 'postgres' || asked.seals !== true) return snapshotOf(asked, await statement(db), null);
+  // SQLite has no `log_object`: the environments' newest changes in a statement of their own, by the keys the vault
+  // computes, the places asked with no row among them (`gone`, which Postgres's statement answers itself). Both in one
+  // transaction, one snapshot of the file, so that a change committed between them is never a row's seal against a
+  // newer one (review r6); inside a decision's, a savepoint of it.
+  return store.oneSnapshot(db, async (on) => {
+    const raw = await statement(on);
+    const rowless = (raw.placeIds ?? []).filter((id) => !raw.environments.some((row) => row.id === id));
+    return snapshotOf(asked, raw, await store.newestSeals(on, [...raw.environments.map(({ id }) => id), ...rowless].map((id) => ({ kind: 'environment' as const, id }))), rowless);
+  });
+}
+
+/** A snapshot from its statement's row; on SQLite, with the newest seals and the rowless places read beside it. */
+function snapshotOf(asked: Asked, raw: Raw, newest: Map<string, Buffer | null> | null, rowless: readonly string[] = []): Snapshot {
+  const gone = newest === null
+    ? (raw.gone ?? []).map(({ id, newest: last }) => [id, hex(last)] as const)
+    : rowless.flatMap((id) => (newest.has(objectKey({ kind: 'environment', id })) ? [[id, newest.get(objectKey({ kind: 'environment', id })) ?? null] as const] : []));
   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),
-    }])),
+    newestSettings: asked.settings !== true ? undefined : raw.settings == null ? null : entryOf(raw.settings),
+    environments: new Map<string, EnvironmentRow>([...gone.map(([id, last]) => [id, store.goneEnvironment(id, last)] as const), ...raw.environments.map(({ id, projectId, slug, owner, parentId, deleted, archived, ...sealed }) => [id, {
+      projectId, slug, owner, parentId,
+      deleted: Boolean(deleted),
+      archived: Boolean(archived),
+      ...(asked.seals === true ? {
+        sealed: store.environmentSeal(
+          { id, projectId, slug, owner, parentId, protected: sealed.protected == null ? null : Boolean(sealed.protected), archived: Boolean(sealed.ownArchived), projectArchived: Boolean(sealed.projectArchived) },
+          hex(sealed.seal),
+          newest === null ? hex(sealed.newest) : newest.get(objectKey({ kind: 'environment', id })) ?? null,
+        ),
+      } : {}),
+    }] as const)]),
     ended: new Set(raw.ended.map((seq) => BigInt(seq))),
     released: Number(raw.released ?? 0),
     head: raw.head === null ? null : {
@@ -159,11 +206,24 @@ type Raw = {
   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 }[];
+  settings?: RawEntry | null;
+  environments: {
+    id: string; projectId: string; slug: string; owner: string | null; parentId: string | null; deleted: boolean | number; archived: boolean | number;
+    /** With `asked.seals`: the object's own columns, the row's seal and, on Postgres, its newest change's, as hex. */
+    protected?: boolean | number | null; ownArchived?: boolean | number; projectArchived?: boolean | number; seal?: string | null; newest?: string | null;
+  }[];
+  /** With `asked.seals`, on Postgres: the places asked that the log holds a change of and no row answers to. */
+  gone?: { id: string; newest: string | null }[];
+  /** With `asked.seals`, on SQLite: every place id asked, row or none. */
+  placeIds?: string[];
   ended: Int[];
   released: Int | null;
 };
 
+function hex(value: string | null | undefined): Buffer | null {
+  return value == null ? null : Buffer.from(value, 'hex');
+}
+
 /** An entry as the chain's codec reads it, from what `entryJson` wrote. */
 export function entryOf(raw: RawEntry): StoredEntry {
   return {