@coffre/vault 0.14.3 → 0.14.5

package/dist/cloudflare.d.ts

@@ -1,4 +1,4 @@
-import { a as KekUnavailableError, c as awsKms, d as Kek, f as VaultConfig, i as KekProvider, l as checkpointMessage, n as AwsKmsOptions, o as SecretContext, p as derivedSigningKey, r as KekBadClaimError, s as WrappedDek, t as AwsCredentials, u as verifyCheckpoint } from "./index-CIq4i_KT.js";
+import { a as KekUnavailableError, c as awsKms, d as Kek, f as VaultConfig, i as KekProvider, l as checkpointMessage, n as AwsKmsOptions, o as SecretContext, p as derivedSigningKey, r as KekBadClaimError, s as WrappedDek, t as AwsCredentials, u as verifyCheckpoint } from "./index-DQ-FKVF3.js";
 import { AdmitInput, ChangePolicyInput, EndReferencesInput, ReferenceInput, RemoveInput, RewrapInput, SetAccessInput, SetSettingsInput, UnwrapInput, Vault, VerifyLogInput, WrapInput } from "@coffre/core/vault";
 import { PostgresDatabase, PostgresDatabase as PostgresDatabase$1, postgres } from "@coffre/db/hyperdrive";
 import { WorkerEntrypoint } from "cloudflare:workers";
@@ -16,10 +16,7 @@ export type WorkersVaultConfig = VaultConfig & {
  */
 export declare class VaultEntrypoint extends WorkerEntrypoint implements Vault {
   #private;
-  unwrap(input: UnwrapInput): Promise<import("@coffre/core/vault").Outcome<{
-    keys: string[];
-    accessRevision?: string;
-  }>>;
+  unwrap(input: UnwrapInput): Promise<import("@coffre/core/vault").Outcome<import("@coffre/core/vault").Unwrapped>>;
   wrap(input: WrapInput): Promise<import("@coffre/core/vault").Outcome<import("@coffre/core/vault").Wrapped>>;
   rewrap(input: RewrapInput): Promise<import("@coffre/core/vault").Outcome<import("@coffre/core/vault").Wrapped>>;
   reference(input: ReferenceInput): Promise<import("@coffre/core/vault").Outcome<{

package/dist/cloudflare.js

@@ -1,5 +1,5 @@
-import { a as verifyCheckpoint, i as checkpointMessage, n as KekUnavailableError, o as derivedSigningKey, r as awsKms, s as resolveVaultConfig, t as KekBadClaimError } from "./src-NM5NsYFs.js";
-import { n as prepareVault, t as openVault } from "./vault-B4IivgU8.js";
+import { a as verifyCheckpoint, c as resolveVaultConfig, i as checkpointMessage, n as KekUnavailableError, r as awsKms, s as derivedSigningKey, t as KekBadClaimError } from "./src-Bg0ZeMJW.js";
+import { n as prepareVault, t as openVault } from "./vault-Cbi45kLB.js";
 import { createDatabase } from "@coffre/db";
 import { HyperdrivePool, postgres } from "@coffre/db/hyperdrive";
 import { WorkerEntrypoint } from "cloudflare:workers";

package/dist/{index-CIq4i_KT.d.ts → index-DQ-FKVF3.d.ts}

@@ -36,7 +36,10 @@ type VaultConfig = {
    * service holds the KEK, as AWS KMS does: the vault never sees that key.
    */
   signingKey?: string;
-  /** At most `count` distinct data keys unwrapped per principal in any `windowMinutes`; 1000 in 15 unless set. */
+  /**
+   * At most `count` distinct data keys unwrapped per principal in any `windowMinutes`; 1000 in 15 unless set. The
+   * window is a day at most: the releases it counts are kept a day and an hour (`prune_vault_releases`).
+   */
   bulkLimit?: {
     count: number;
     windowMinutes: number;

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-import { a as KekUnavailableError, c as awsKms, d as Kek, f as VaultConfig, i as KekProvider, l as checkpointMessage, n as AwsKmsOptions, o as SecretContext, p as derivedSigningKey, r as KekBadClaimError, s as WrappedDek, t as AwsCredentials, u as verifyCheckpoint } from "./index-CIq4i_KT.js";
+import { a as KekUnavailableError, c as awsKms, d as Kek, f as VaultConfig, i as KekProvider, l as checkpointMessage, n as AwsKmsOptions, o as SecretContext, p as derivedSigningKey, r as KekBadClaimError, s as WrappedDek, t as AwsCredentials, u as verifyCheckpoint } from "./index-DQ-FKVF3.js";
 export type * from "@coffre/core/vault";
 export { type AwsCredentials, type AwsKmsOptions, type Kek, KekBadClaimError, type KekProvider, KekUnavailableError, type SecretContext, type VaultConfig, type WrappedDek, awsKms, checkpointMessage, derivedSigningKey, verifyCheckpoint };

package/dist/index.js

@@ -1,2 +1,2 @@
-import { a as verifyCheckpoint, i as checkpointMessage, n as KekUnavailableError, o as derivedSigningKey, r as awsKms, t as KekBadClaimError } from "./src-NM5NsYFs.js";
+import { a as verifyCheckpoint, i as checkpointMessage, n as KekUnavailableError, r as awsKms, s as derivedSigningKey, t as KekBadClaimError } from "./src-Bg0ZeMJW.js";
 export { KekBadClaimError, KekUnavailableError, awsKms, checkpointMessage, derivedSigningKey, verifyCheckpoint };

package/dist/node.d.ts

@@ -1,4 +1,4 @@
-import { a as KekUnavailableError, c as awsKms, d as Kek, f as VaultConfig, i as KekProvider, l as checkpointMessage, n as AwsKmsOptions, o as SecretContext, p as derivedSigningKey, r as KekBadClaimError, s as WrappedDek, t as AwsCredentials, u as verifyCheckpoint } from "./index-CIq4i_KT.js";
+import { a as KekUnavailableError, c as awsKms, d as Kek, f as VaultConfig, i as KekProvider, l as checkpointMessage, n as AwsKmsOptions, o as SecretContext, p as derivedSigningKey, r as KekBadClaimError, s as WrappedDek, t as AwsCredentials, u as verifyCheckpoint } from "./index-DQ-FKVF3.js";
 import { Vault, Vault as Vault$1 } from "@coffre/core/vault";
 import { Database } from "@coffre/db";
 import "@coffre/core/access";

package/dist/node.js

@@ -1,5 +1,5 @@
-import { a as verifyCheckpoint, i as checkpointMessage, n as KekUnavailableError, o as derivedSigningKey, r as awsKms, s as resolveVaultConfig, t as KekBadClaimError } from "./src-NM5NsYFs.js";
-import { n as prepareVault, t as openVault } from "./vault-B4IivgU8.js";
+import { a as verifyCheckpoint, c as resolveVaultConfig, i as checkpointMessage, n as KekUnavailableError, r as awsKms, s as derivedSigningKey, t as KekBadClaimError } from "./src-Bg0ZeMJW.js";
+import { n as prepareVault, t as openVault } from "./vault-Cbi45kLB.js";
 import { isUnavailable } from "@coffre/db/dialect";
 import { chmodSync, existsSync, lstatSync, rmSync } from "node:fs";
 import { Agent, createServer, request } from "node:http";

package/dist/{src-NM5NsYFs.js → src-Bg0ZeMJW.js}

@@ -11,6 +11,13 @@ const DEFAULT_BULK_LIMIT = {
 	count: 1e3,
 	windowMs: 9e5
 };
+/**
+* The longest bulk limit window: a day. The releases a window counts are
+* kept a day and an hour (migration 0021's `prune_vault_releases`, and on
+* SQLite `RELEASES_KEPT_MS`), so every window up to it, and one widened
+* since, counts exactly.
+*/
+const MAX_BULK_WINDOW_MINUTES = 1440;
 function key32(value, what) {
 	const raw = Buffer.from(value, "base64");
 	if (raw.length !== 32) throw new Error(`${what} must be 32 bytes, base64; got ${raw.length} bytes`);
@@ -76,7 +83,7 @@ function signingKeys(given, keks) {
 	return [signing, ...derived].filter((key, i, all) => all.findIndex((other) => other.equals(key)) === i);
 }
 function checkBulkLimit({ count, windowMinutes }) {
-	if (!Number.isInteger(count) || count < 1 || !(windowMinutes > 0)) throw new Error("bulkLimit needs a whole count of at least 1 and a window above 0 minutes");
+	if (!Number.isInteger(count) || count < 1 || !(windowMinutes > 0) || windowMinutes > 1440) throw new Error(`bulkLimit needs a whole count of at least 1 and a window above 0 minutes, a day (${MAX_BULK_WINDOW_MINUTES}) at most`);
 	return {
 		count,
 		windowMs: windowMinutes * 6e4
@@ -105,4 +112,4 @@ function checkOwners(emails) {
 	return [...new Set(owners.map((entry) => entry.toLowerCase()))];
 }
 //#endregion
-export { verifyCheckpoint as a, checkpointMessage$1 as i, KekUnavailableError$1 as n, derivedSigningKey as o, awsKms as r, resolveVaultConfig as s, KekBadClaimError$1 as t };
+export { verifyCheckpoint as a, resolveVaultConfig as c, checkpointMessage$1 as i, KekUnavailableError$1 as n, MAX_BULK_WINDOW_MINUTES as o, awsKms as r, derivedSigningKey as s, KekBadClaimError$1 as t };

package/dist/{vault-B4IivgU8.js → vault-Cbi45kLB.js}

@@ -1,4 +1,5 @@
-import { ACCESS_ACTIONS, ACCESS_ACTIONS as ACCESS_ACTIONS$1, POLICY_REVISION, accessRevision, checkpointMessage, checkpointVerifier, describeAccessFault, handsBack, policyRevision } from "@coffre/core/vault";
+import { o as MAX_BULK_WINDOW_MINUTES } from "./src-Bg0ZeMJW.js";
+import { ACCESS_ACTIONS, ACCESS_ACTIONS as ACCESS_ACTIONS$1, POLICY_REVISION, USE_METADATA_LENGTH, accessRevision, checkpointMessage, checkpointVerifier, describeAccessFault, handsBack, policyRevision } from "@coffre/core/vault";
 import { DEK_BYTES, KEY_CHECK, KEY_CHECK_CONTEXT, KEY_CHECK_VALUE, KekBadClaimError, KekCancelledError, KekUnavailableError, LocalKekProvider } from "@coffre/core/kek";
 import { prepared, tablesOf } from "@coffre/db";
 import { createHash, createHmac, hkdfSync, randomUUID, timingSafeEqual } from "node:crypto";
@@ -6,9 +7,9 @@ import { DEFAULT_POLICY, EVERYWHERE, EVERY_ENVIRONMENT, FIXED_ROLES, INSTANCE_RO
 import { GENESIS_HASH, deriveLogKey, verifyEntries } from "@coffre/core/audit";
 import { checkContext, ownerKey } from "@coffre/core/envelope";
 import { TOMBSTONE, shownMember } from "@coffre/core/schemas";
-import { SNAPSHOT, clockMillis, engineOf, forUpdate, isUnavailable, isUniqueViolation, rowsOf, tombstone, truth } from "@coffre/db/dialect";
+import { SNAPSHOT, changedRows, clockMillis, engineOf, forUpdate, isUnavailable, isUniqueViolation, rowsOf, tombstone, truth } from "@coffre/db/dialect";
 import { accessEntriesAbout, everyProjectConversion, insertGrant, liveProjects, newestAccess, readGrants, reportStands, roleColumns, storedRole } from "@coffre/db/grants";
-import { LogHeadMismatch, appendEntries, entryColumns, lockLogHead, missingEntry, newestAuthentic, newestVaultEntries, withinBytes } from "@coffre/db/log";
+import { LogHeadMismatch, appendEntries, entryColumns, lockLogHead, lockLogHeadQueued, missingEntry, newestAuthentic, newestVaultEntries, withinBytes } from "@coffre/db/log";
 import { and, asc, desc, eq, gt, gte, inArray, isNotNull, isNull, lt, lte, or, sql } from "drizzle-orm";
 //#region src/checkpoint.ts
 const PKCS8_ED25519 = [
@@ -189,6 +190,33 @@ async function boundLockWaits(tx, ms, statements = false) {
 	const bound = String(Math.trunc(ms));
 	await tx.execute(statements ? sql`SELECT set_config('lock_timeout', ${bound}, true), set_config('statement_timeout', ${bound}, true)` : sql.raw(`SET LOCAL lock_timeout = ${bound}`));
 }
+/**
+* How long a release is kept: the longest bulk limit window
+* (`MAX_BULK_WINDOW_MINUTES`, a day), and an hour, a margin for the
+* database's clock stepping back between a prune and a later count, which
+* is seconds. Migration 0021's `prune_vault_releases` holds the same, a day
+* and an hour, in its own SQL: a longer window takes a migration too.
+*/
+const RELEASES_KEPT_MS = MAX_BULK_WINDOW_MINUTES * 6e4 + 36e5;
+/**
+* Delete up to `atMost` rows of `vault_releases` released over
+* `RELEASES_KEPT_MS` before the database's clock: what no bulk count can
+* read again. On Postgres the vault's login deletes no row itself, and asks
+* `prune_vault_releases`, which deletes only those (migration 0021). How
+* many went.
+*/
+async function pruneReleases(db, atMost) {
+	if (engineOf(db) === "postgres") {
+		const [row] = await rowsOf(db, sql`SELECT prune_vault_releases(${atMost}::int) AS pruned`);
+		return row.pruned;
+	}
+	const { vaultReleases } = tablesOf(db);
+	const old = db.select({
+		principal: vaultReleases.principal,
+		key: vaultReleases.key
+	}).from(vaultReleases).where(lt(vaultReleases.releasedAt, sql`${clockMillis(db)} - ${RELEASES_KEPT_MS}`)).limit(atMost);
+	return changedRows(await db.delete(vaultReleases).where(sql`(${vaultReleases.principal}, ${vaultReleases.key}) IN ${old}`));
+}
 /** The database's clock, now. */
 async function now(db) {
 	const [{ at }] = await clock(db);
@@ -1216,17 +1244,16 @@ function snapshotQuery$1(asked) {
         WHERE author = 'vault' AND action = 'reference.end' AND decision = 'allow' AND related_seq = ANY(${references})
       ),
       'released', ${released === void 0 ? sql`0` : sql`(
-          SELECT count(DISTINCT key) FROM (
-            -- A read of one key names it; of several at one place, lists them (readsByPlace, vault.ts). An entry, or an
-            -- item of its list, that names no key, which only a forged entry is, counts as one key of its own.
-            SELECT coalesce(e.secret_id::text, CASE jsonb_typeof(one -> 'secretId') WHEN 'string' THEN one ->> 'secretId' END, 'entry:' || e.seq) FROM audit_log e
-            -- Each item of a list, never what lax paths would make of an object; silent, as strict paths fail on what is missing.
-            LEFT JOIN LATERAL jsonb_path_query(CASE WHEN e.secret_id IS NULL THEN e.metadata::jsonb END, 'strict $.secrets ? (@.type() == "array")[*]', '{}', true) AS one ON true
-            WHERE e.author = 'vault' AND e.actor = ${released.principal} AND e.action = 'secret.read' AND e.decision = 'allow'
-              AND e.occurred_at > ${NOW$1} + ${released.clockOffsetMs} - ${released.windowMs}
-            UNION ALL SELECT unnest(${sql.param([...released.keys])}::text[])
-          ) AS released (key)
-        )`}
+          -- The keys released within the window, but those asked for, up to one past the cap: a row for each key the
+          -- principal was ever released, however many reads of them the log holds (vault_releases, which the database
+          -- keeps from it). The bound is a subquery, evaluated once: clock_timestamp() alone is volatile, and runs a row.
+          SELECT count(*) FROM (
+            SELECT 1 FROM vault_releases
+            WHERE principal = ${released.principal} AND released_at > (SELECT ${NOW$1} + ${released.clockOffsetMs} - ${released.windowMs})
+              AND key <> ALL(${sql.param([...released.keys])}::text[])
+            LIMIT ${released.cap + 1}
+          ) AS before
+        ) + (SELECT count(DISTINCT key) FROM unnest(${sql.param([...released.keys])}::text[]) AS asked (key))`}
     ) AS snapshot`;
 }
 //#endregion
@@ -1307,17 +1334,14 @@ function snapshotQuery(asked) {
         WHERE author = 'vault' AND action = 'reference.end' AND decision = 'allow' AND related_seq IN (SELECT value FROM json_each(${references}))
       )),
       'released', ${released === void 0 ? sql`0` : sql`(
-          SELECT count(DISTINCT key) FROM (
-            -- A read of one key names it; of several at one place, lists them (readsByPlace, vault.ts). An entry, or an
-            -- item of its list, that names no key, which only a forged entry is, counts as one key of its own.
-            SELECT coalesce(e.secret_id, CASE WHEN one.type = 'object' AND json_type(one.value, '$.secretId') = 'text' THEN json_extract(one.value, '$.secretId') END, 'entry:' || e.seq) AS key
-            FROM audit_log e
-            LEFT JOIN json_each(CASE WHEN e.secret_id IS NULL AND json_type(e.metadata, '$.secrets') = 'array' THEN e.metadata END, '$.secrets') AS one
-            WHERE e.author = 'vault' AND e.actor = ${released.principal} AND e.action = 'secret.read' AND e.decision = 'allow'
-              AND e.occurred_at > ${NOW} + ${released.clockOffsetMs} - ${released.windowMs}
-            UNION ALL SELECT value FROM json_each(${JSON.stringify(released.keys)})
+          -- The keys released within the window, but those asked for, up to one past the cap (snapshot.postgres.ts).
+          SELECT count(*) FROM (
+            SELECT 1 FROM vault_releases
+            WHERE principal = ${released.principal} AND released_at > ${NOW} + ${released.clockOffsetMs} - ${released.windowMs}
+              AND key NOT IN (SELECT value FROM json_each(${JSON.stringify(released.keys)}))
+            LIMIT ${released.cap + 1}
           )
-        )`}
+        ) + (SELECT count(DISTINCT value) FROM json_each(${JSON.stringify(released.keys)}))`}
     ) AS snapshot`;
 }
 //#endregion
@@ -1326,7 +1350,7 @@ async function snapshot(db, asked) {
 	const read = () => readOnce(db, asked);
 	const first = await read();
 	if (asked.head !== true || first.head !== null && current(first.head)) return first;
-	if (first.head === null) await lockLogHead(db);
+	if (first.head === null) await (asked.waiters === void 0 ? lockLogHead(db) : lockLogHeadQueued(db, 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");
 	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`);
@@ -1819,6 +1843,31 @@ const LOCK_TIMEOUT_MS = 15e3;
 * again later.
 */
 const READ_LOCK_TIMEOUT_MS = 3e3;
+/**
+* How long a whole read call may take, from its start to its answer, its
+* refusal's entries, the record of a vault key's check and, with a key
+* service, its intent and its own budget (added) included: each transaction's waits are bounded by what is left of it, and
+* past it the call fails as unavailable (`Overdue`) rather than start
+* another. So a caller hears within it, ok or 503, never tens of seconds later.
+*/
+const READ_DEADLINE_MS = 5e3;
+/** How many releases a checkpoint prunes at most: one short statement, a few each scheduled run. */
+const RELEASES_PRUNED = 1e4;
+/** A read's call past its deadline (`READ_DEADLINE_MS`): unavailable, as a statement past its bound (57014) is. */
+var Overdue = class extends Error {
+	code = "57014";
+	constructor() {
+		super("this read took longer than it may: ask again shortly");
+		this.name = "Overdue";
+	}
+};
+/** The bound of a transaction of a call due at `deadline`: `ms`, or what is left of the call, if less. */
+function within(deadline, ms) {
+	if (deadline === void 0) return ms;
+	const left = deadline - Date.now();
+	if (left <= 0) throw new Overdue();
+	return Math.min(ms, left);
+}
 /** A member: `user:<email>` or `token:<name>`. */
 const PRINCIPAL = /^(user|token):[^\s:][^\s]*$/;
 /** A person, and a service account: only a person sets one up (`givesService`). */
@@ -1999,16 +2048,18 @@ var VaultService = class {
 		return reads.at + this.#prepared.options.clockOffset();
 	}
 	/** What a decision about `principals` reads, and `asked` besides, in one statement: under the head when `head` is set. */
-	#snapshot(tx, principals, asked, head) {
+	#snapshot(tx, principals, asked, head, reading = false) {
 		const { released, ...rest } = asked;
 		return snapshot(tx, {
 			...rest,
 			principals,
 			head,
+			...reading ? { waiters: 16 } : {},
 			...released === void 0 ? {} : { released: {
 				...released,
 				windowMs: this.#config.bulkLimit.windowMs,
-				clockOffsetMs: this.#prepared.options.clockOffset()
+				clockOffsetMs: this.#prepared.options.clockOffset(),
+				cap: this.#config.bulkLimit.count
 			} }
 		});
 	}
@@ -2037,19 +2088,23 @@ var VaultService = class {
 	/** `#decide`, once the vault is settled. */
 	async #decideNow(principals, decide, how = {}) {
 		const reports = [];
+		const due = how.reads === true ? {
+			...how,
+			deadline: how.deadline ?? Date.now() + 5e3
+		} : how;
 		for (let attempt = 1;; attempt += 1) try {
-			return await this.#decideOnce(principals, decide, reports, how);
+			return await this.#decideOnce(principals, decide, reports, due);
 		} catch (error) {
 			if (attempt < 3 && (error instanceof Retry || isUniqueViolation(error))) continue;
 			throw error;
 		}
 	}
-	async #decideOnce(principals, decide, reports, { late = false, asked = {}, reads: shared = false }) {
+	async #decideOnce(principals, decide, reports, { late = false, asked = {}, reads: shared = false, deadline }) {
 		try {
 			const result = await this.#db.transaction(async (tx) => {
-				await boundLockWaits(tx, shared ? READ_LOCK_TIMEOUT_MS : LOCK_TIMEOUT_MS, shared);
+				await boundLockWaits(tx, shared ? within(deadline, READ_LOCK_TIMEOUT_MS) : LOCK_TIMEOUT_MS, shared);
 				const members = principals.length === 0 ? /* @__PURE__ */ new Map() : await lockMembers(tx, principals, shared);
-				const reads = await this.#snapshot(tx, principals, asked, !late);
+				const reads = await this.#snapshot(tx, principals, asked, !late, shared);
 				const d = {
 					tx,
 					members,
@@ -2092,7 +2147,8 @@ var VaultService = class {
 			if (!(error instanceof Refused || error instanceof Outage)) throw error;
 			const entries = [...reports, ...readsByPlace(error.entries)];
 			if (entries.length > 0) await this.#db.transaction(async (tx) => {
-				await boundLockWaits(tx, LOCK_TIMEOUT_MS);
+				await boundLockWaits(tx, shared ? within(deadline, READ_LOCK_TIMEOUT_MS) : LOCK_TIMEOUT_MS, shared);
+				if (shared) await lockLogHeadQueued(tx, 16);
 				await this.#append(tx, entries);
 			});
 			this.#reported(reports);
@@ -2430,6 +2486,7 @@ var VaultService = class {
 	}
 	async unwrap(input) {
 		const { principal } = input;
+		const use = input.use === void 0 ? null : useEntry(principal, input, input.use);
 		validateText(input.purpose);
 		if (input.keepsSensitive !== void 0 && typeof input.keepsSensitive !== "boolean") throw new Error("keepsSensitive is true, false or absent");
 		if (input.accessRevision !== void 0 && typeof input.accessRevision !== "string") throw new Error("accessRevision names an answer of access, or is absent");
@@ -2476,6 +2533,16 @@ var VaultService = class {
 		};
 		if (viaOk.includes(false)) return this.#refuseVersions(principal, "bad_claim", items.map((item) => entry(item.secret, "deny", "bad_claim")), { asked: input.accessRevision });
 		if (throughOk.includes(false)) return this.#refuseVersions(principal, "bad_claim", items.map((item) => entry(item.secret, "deny", "bad_claim")), { asked: input.accessRevision });
+		if (use !== null && (use.environmentId !== null || use.projectId !== null)) {
+			if (!items.some((item, i) => {
+				const fork = throughs[i] === null ? void 0 : forks.get(throughs[i]);
+				const place = fork === void 0 ? sealed[i]?.holder ?? item.secret : {
+					projectId: fork.projectId,
+					environmentId: throughs[i]
+				};
+				return (use.environmentId === null || place.environmentId === use.environmentId) && (use.projectId === null || place.projectId === use.projectId);
+			})) return this.#refuseVersions(principal, "bad_claim", items.map((item) => entry(item.secret, "deny", "bad_claim")), { asked: input.accessRevision });
+		}
 		const ends = sealed.flatMap((seal) => seal === null ? [] : [seal.seq]);
 		const remote = items.some(({ wrapped }) => this.#remote(this.#config.keks.providerOf(wrapped)));
 		return this.#keys({
@@ -2489,7 +2556,8 @@ var VaultService = class {
 			vet: ends.length === 0 ? void 0 : async (_, reads) => sealed.map((seal) => seal !== null && reads.ended.has(seal.seq) ? "ended" : null),
 			remote,
 			entry,
-			input
+			input,
+			...use === null ? {} : { also: [use] }
 		}, (contextOf) => items.map(({ secret, wrapped }) => async (operation) => {
 			const key = await this.#open(wrapped, contextOf(secret), operation);
 			return key && {
@@ -2504,7 +2572,8 @@ var VaultService = class {
 					key.fill(0);
 				}
 			}),
-			...input.accessRevision === void 0 ? {} : { accessRevision: input.accessRevision }
+			...input.accessRevision === void 0 ? {} : { accessRevision: input.accessRevision },
+			...use === null ? {} : { used: true }
 		}));
 	}
 	async wrap(input) {
@@ -2685,9 +2754,13 @@ var VaultService = class {
 	async #keys(call, operations, result) {
 		const { action, principal, secrets, entry } = call;
 		for (const secret of secrets) entry(secret, "allow", null);
-		const wrongKek = await this.#kekMismatch();
+		const deadline = Date.now() + READ_DEADLINE_MS + (call.remote ? this.#prepared.options.keyBudgetMs : 0);
+		const wrongKek = await this.#kekMismatch(deadline);
 		if (wrongKek !== null) return this.#decide([], async () => {
 			throw new Refused(refusal("wrong_kek", wrongKek), secrets.map((secret) => entry(secret, "deny", "wrong_kek")));
+		}, {
+			reads: true,
+			deadline
 		});
 		const owners = /* @__PURE__ */ new Map();
 		const check = async (d) => {
@@ -2776,7 +2849,8 @@ var VaultService = class {
 				}], [], d.reads)).seqStart };
 			}, {
 				asked: reads,
-				reads: true
+				reads: true,
+				deadline
 			});
 			if (!intent.ok) return intent;
 			intentSeq = intent.seq;
@@ -2799,7 +2873,7 @@ var VaultService = class {
 				if (first === void 0 || first === null) return;
 				throw new Refused(refusal(first, MESSAGES[first]), secrets.map((secret, item) => outcomeEntry(secret, item, "deny", codes[item] ?? first)));
 			});
-			const { outcomes, expired } = await settle(operations((secret) => context(secret, owners.get(secret.environmentId))), this.#prepared.options.keyBudgetMs);
+			const { outcomes, expired } = await settle(operations((secret) => context(secret, owners.get(secret.environmentId))), within(deadline, this.#prepared.options.keyBudgetMs));
 			const done = outcomes.flatMap((outcome) => outcome.ok ? [outcome.value] : []);
 			try {
 				const entries = () => secrets.map((secret, i) => outcomeEntry(secret, i, "deny", outcomes[i].ok ? "withheld" : outcomes[i].code));
@@ -2810,13 +2884,13 @@ var VaultService = class {
 				if (expired) throw new Outage(new KekUnavailableError("key operation exceeded its deadline"), entries());
 				if (done.length < outcomes.length) throw new Refused(refusal("bad_claim", MESSAGES.bad_claim), entries());
 				if (late) {
-					d.reads = await this.#snapshot(d.tx, [principal], reads, true);
+					d.reads = await this.#snapshot(d.tx, [principal], reads, true, true);
 					d.at = this.#at(d.reads);
 					await decided(d);
 					if (secrets.flatMap((secret, i) => [secret, call.places?.[i] ?? secret]).some((place) => d.reads.environments.get(place.environmentId)?.deleted ?? false)) throw new Refused(refusal("deleted", MESSAGES.deleted), secrets.map((secret, i) => outcomeEntry(secret, i, "deny", "deleted")));
 				}
 				const released = secrets.map((secret, i) => outcomeEntry(secret, i, "allow", null));
-				d.log.push(...released);
+				d.log.push(...released, ...call.also ?? []);
 				const answer = result(done);
 				if (action !== "secret.read") d.after.push((seqOf) => Object.assign(answer, { seqs: released.map(seqOf) }));
 				return answer;
@@ -2826,7 +2900,8 @@ var VaultService = class {
 		}, {
 			late,
 			asked: reads,
-			reads: true
+			reads: true,
+			deadline
 		});
 	}
 	/**
@@ -3854,10 +3929,10 @@ var VaultService = class {
 	* service that cannot answer leaves it undecided: the error is thrown,
 	* and the next call asks again.
 	*/
-	async #kekMismatch() {
+	async #kekMismatch(deadline) {
 		const prepared = this.#prepared;
 		if (!prepared.kekChecked) {
-			const wrong = await this.#checkKeks();
+			const wrong = await this.#checkKeks(deadline);
 			if (!prepared.kekChecked) {
 				prepared.wrongKek = wrong;
 				prepared.kekChecked = true;
@@ -3871,15 +3946,16 @@ var VaultService = class {
 	* keys it wrapped, if there are any; then its check value is recorded.
 	* A KEK that opens neither is not the one that wrapped the data.
 	*/
-	async #checkKeks() {
+	async #checkKeks(deadline) {
 		const superseded = await this.#settled();
 		if (superseded !== null) return superseded;
 		const checks = await this.#checkValues(this.#db);
 		const budget = this.#prepared.options.keyBudgetMs;
 		for (const kek of this.#config.keks.all) {
+			const spend = within(deadline, budget);
 			const operation = {
-				deadline: Date.now() + budget,
-				signal: AbortSignal.timeout(budget)
+				deadline: Date.now() + spend,
+				signal: AbortSignal.timeout(spend)
 			};
 			const opens = async (wrapped, context, expected) => {
 				try {
@@ -3914,6 +3990,7 @@ var VaultService = class {
 			if (samples.length > 0 && proof === null) return mismatch;
 			const wrapped = await kek.wrap(Buffer.from(KEY_CHECK_VALUE), KEY_CHECK_CONTEXT, operation);
 			await this.#db.transaction(async (tx) => {
+				await boundLockWaits(tx, within(deadline, READ_LOCK_TIMEOUT_MS), true);
 				await lockLogHead(tx);
 				if ((await this.#checkValues(tx)).has(`${kek.provider}:${kek.keyId}`)) return;
 				await this.#append(tx, [{
@@ -4057,9 +4134,9 @@ var VaultService = class {
 		const { wrongKek, logKeys } = this.#prepared;
 		const { walks } = this.#prepared.options;
 		const found = [];
-		let seen = null;
+		let seen;
 		const resumed = await this.#db.transaction(async (tx) => {
-			seen = (await newestCheckpointEntry(tx))?.seq ?? null;
+			seen = await newestCheckpointEntry(tx);
 			await this.#sweep(tx, found);
 			const from = await this.#resume(tx, "newest");
 			if (!from.ok) return from;
@@ -4089,7 +4166,7 @@ var VaultService = class {
 			if (!isUnavailable(error)) throw error;
 			stalled = `the rehash of the past did not run, and goes on where it was next time: ${error.message}`;
 		}
-		return this.#decide([], async (d) => {
+		const decided = await this.#decide([], async (d) => {
 			for (const entry of found) if (!d.reports.includes(entry)) d.reports.push(entry);
 			const head = await lockLogHead(d.tx);
 			const latest = await latestVaultEntry(d.tx, [CHECKPOINT]);
@@ -4111,10 +4188,14 @@ var VaultService = class {
 				reason: scrub.reason
 			});
 			const newest = latest === void 0 ? null : JSON.parse(latest.metadata);
-			if (stalled !== null || ((await newestCheckpointEntry(d.tx))?.seq ?? null) !== seen) {
+			if (stalled !== null || ((await newestCheckpointEntry(d.tx))?.seq ?? null) !== (seen?.seq ?? null)) {
 				const standing = await this.#standingRefusal(d.tx);
 				if (standing !== null) throw refused("log_broken", standing);
 				if (stalled === null && newest !== null) return { checkpoint: signedPart(newest) };
+			} else if (seen?.decision === "deny" && walked.ok) {
+				const standing = await this.#standingRefusal(d.tx);
+				const named = typeof standing?.failedAtSeq === "number" ? BigInt(standing.failedAtSeq) : null;
+				if (named !== null && named <= walked.from.at.seq && !await this.#entryHolds(d.tx, named)) throw refused("log_broken", standing);
 			}
 			if (newest !== null && latest.seq === head.nextSeq - 1n && latest.relatedSeq === latest.seq - 1n) return { checkpoint: signedPart(newest) };
 			if (newest !== null && !await carries(d.tx, newest)) throw refused("log_broken", { reason: `the log up to entry ${newest.seq} is not the prefix the last checkpoint signed` });
@@ -4185,6 +4266,13 @@ var VaultService = class {
 				warning: stalled
 			};
 		});
+		if (!decided.ok) return decided;
+		const pruned = await pruneReleases(this.#db, RELEASES_PRUNED).then(() => null, (error) => `the releases the bulk limit counts were not pruned, and the next checkpoint tries again: ${error.message}`);
+		if (pruned === null) return decided;
+		return {
+			...decided,
+			warning: decided.warning === void 0 ? pruned : `${decided.warning}; ${pruned}`
+		};
 	}
 	/**
 	* The walk on from where a checkpoint resumes, no further than `limit`
@@ -4252,6 +4340,30 @@ var VaultService = class {
 		};
 	}
 	/**
+	* Whether entry `seq` is as the walk checks each: there, its hash its
+	* own, linked to the entry before, and the vault's under its MAC; and the
+	* entry after it, if any, linked to it, for a refusal can name either side
+	* of a broken link (`forward`, at the end of a batch).
+	*/
+	async #entryHolds(db, seq) {
+		const found = await entriesAt(db, seq === 0n ? [seq, seq + 1n] : [
+			seq - 1n,
+			seq,
+			seq + 1n
+		]);
+		const entry = found.get(seq);
+		const before = seq === 0n ? { hash: GENESIS_HASH } : found.get(seq - 1n);
+		if (entry === void 0 || before === void 0) return false;
+		const after = found.get(seq + 1n);
+		if (after !== void 0 && !after.prevHash.equals(entry.hash)) return false;
+		return verifyEntries([entry], {
+			keys: this.#keysFor(entry),
+			chainOnly: ["app"],
+			startSeq: seq,
+			startPrevHash: before.hash
+		}).ok;
+	}
+	/**
 	* The newest refusal for a broken log since the newest checkpoint was
 	* signed, by the vault's MAC, as it said: it stands, for every
 	* verification and checkpoint, until a checkpoint is signed, which takes
@@ -4634,6 +4746,39 @@ function validateText(value) {
 	if (typeof value !== "string" || /[\uD800-\uDFFF]/u.test(value)) throw new Error("key request strings must be well-formed Unicode");
 }
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/**
+* The app's `credential.use` entry, as the vault appends it beside a read
+* (`UnwrapInput.use`): what the app wrote, checked to be what an entry
+* holds, in its reader's name. The app wrote it under the head itself
+* before 0.14.5; it describes the read, and decides nothing.
+*/
+function useEntry(principal, correlation, use) {
+	const id = (value, name) => {
+		if (value !== null && (typeof value !== "string" || !UUID.test(value))) throw new Error(`a use's ${name} must be a lowercase UUID or null`);
+		return value;
+	};
+	if (typeof use.metadata !== "string" || use.metadata.length > USE_METADATA_LENGTH) throw new Error(`a use's metadata must be a JSON object of at most ${USE_METADATA_LENGTH} characters`);
+	if (use.sourceIp !== null) validateText(use.sourceIp);
+	validateText(use.metadata);
+	let metadata;
+	try {
+		metadata = JSON.parse(use.metadata);
+	} catch {
+		metadata = void 0;
+	}
+	if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata)) throw new Error(`a use's metadata must be a JSON object of at most ${USE_METADATA_LENGTH} characters`);
+	return {
+		actor: principal,
+		action: "credential.use",
+		decision: "allow",
+		projectId: id(use.projectId, "projectId"),
+		environmentId: id(use.environmentId, "environmentId"),
+		operationId: correlation.operationId ?? null,
+		requestId: correlation.requestId ?? null,
+		sourceIp: use.sourceIp,
+		metadata: use.metadata
+	};
+}
 /** The caller's ids go into the log as they are: a request id is text, an operation id a lowercase UUID. */
 function validateCorrelation(input) {
 	if (input.requestId != null) validateText(input.requestId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/vault",
-  "version": "0.14.3",
+  "version": "0.14.5",
   "description": "coffre's vault: keys, grants and members, in the database the app uses, as a Cloudflare Worker or on Node.",
   "license": "MIT",
   "repository": {
@@ -36,8 +36,8 @@
   },
   "dependencies": {
     "drizzle-orm": "0.45.2",
-    "@coffre/core": "0.14.3",
-    "@coffre/db": "0.14.3"
+    "@coffre/core": "0.14.5",
+    "@coffre/db": "0.14.5"
   },
   "devDependencies": {
     "@types/node": "26.1.1",

package/src/config.ts

@@ -11,6 +11,14 @@ export type BulkLimit = { count: number; windowMs: number };
  */
 export const DEFAULT_BULK_LIMIT: BulkLimit = { count: 1000, windowMs: 15 * 60_000 };
 
+/**
+ * The longest bulk limit window: a day. The releases a window counts are
+ * kept a day and an hour (migration 0021's `prune_vault_releases`, and on
+ * SQLite `RELEASES_KEPT_MS`), so every window up to it, and one widened
+ * since, counts exactly.
+ */
+export const MAX_BULK_WINDOW_MINUTES = 24 * 60;
+
 /** The vault as it runs: keys decoded, emails checked. */
 export type ResolvedVaultConfig = {
   keks: KekRegistry;
@@ -61,7 +69,10 @@ export type VaultConfig = {
    * service holds the KEK, as AWS KMS does: the vault never sees that key.
    */
   signingKey?: string;
-  /** At most `count` distinct data keys unwrapped per principal in any `windowMinutes`; 1000 in 15 unless set. */
+  /**
+   * At most `count` distinct data keys unwrapped per principal in any `windowMinutes`; 1000 in 15 unless set. The
+   * window is a day at most: the releases it counts are kept a day and an hour (`prune_vault_releases`).
+   */
   bulkLimit?: { count: number; windowMinutes: number };
   /**
    * @deprecated Gone in 0.10, and refused: each key says who sees it now. Mark
@@ -176,8 +187,8 @@ function signingKeys(given: string | undefined, keks: { provider: KekProvider; s
 
 
 function checkBulkLimit({ count, windowMinutes }: { count: number; windowMinutes: number }): BulkLimit {
-  if (!Number.isInteger(count) || count < 1 || !(windowMinutes > 0)) {
-    throw new Error('bulkLimit needs a whole count of at least 1 and a window above 0 minutes');
+  if (!Number.isInteger(count) || count < 1 || !(windowMinutes > 0) || windowMinutes > MAX_BULK_WINDOW_MINUTES) {
+    throw new Error(`bulkLimit needs a whole count of at least 1 and a window above 0 minutes, a day (${MAX_BULK_WINDOW_MINUTES}) at most`);
   }
   return { count, windowMs: windowMinutes * 60_000 };
 }

package/src/snapshot.postgres.ts

@@ -82,16 +82,15 @@ export function snapshotQuery(asked: Asked): SQL {
       'released', ${released === undefined
         ? sql`0`
         : sql`(
-          SELECT count(DISTINCT key) FROM (
-            -- A read of one key names it; of several at one place, lists them (readsByPlace, vault.ts). An entry, or an
-            -- item of its list, that names no key, which only a forged entry is, counts as one key of its own.
-            SELECT coalesce(e.secret_id::text, CASE jsonb_typeof(one -> 'secretId') WHEN 'string' THEN one ->> 'secretId' END, 'entry:' || e.seq) FROM audit_log e
-            -- Each item of a list, never what lax paths would make of an object; silent, as strict paths fail on what is missing.
-            LEFT JOIN LATERAL jsonb_path_query(CASE WHEN e.secret_id IS NULL THEN e.metadata::jsonb END, 'strict $.secrets ? (@.type() == "array")[*]', '{}', true) AS one ON true
-            WHERE e.author = 'vault' AND e.actor = ${released.principal} AND e.action = 'secret.read' AND e.decision = 'allow'
-              AND e.occurred_at > ${NOW} + ${released.clockOffsetMs} - ${released.windowMs}
-            UNION ALL SELECT unnest(${sql.param([...released.keys])}::text[])
-          ) AS released (key)
-        )`}
+          -- The keys released within the window, but those asked for, up to one past the cap: a row for each key the
+          -- principal was ever released, however many reads of them the log holds (vault_releases, which the database
+          -- keeps from it). The bound is a subquery, evaluated once: clock_timestamp() alone is volatile, and runs a row.
+          SELECT count(*) FROM (
+            SELECT 1 FROM vault_releases
+            WHERE principal = ${released.principal} AND released_at > (SELECT ${NOW} + ${released.clockOffsetMs} - ${released.windowMs})
+              AND key <> ALL(${sql.param([...released.keys])}::text[])
+            LIMIT ${released.cap + 1}
+          ) AS before
+        ) + (SELECT count(DISTINCT key) FROM unnest(${sql.param([...released.keys])}::text[]) AS asked (key))`}
     ) AS snapshot`;
 }

package/src/snapshot.sqlite.ts

@@ -88,16 +88,13 @@ export function snapshotQuery(asked: Asked): SQL {
       'released', ${released === undefined
         ? sql`0`
         : sql`(
-          SELECT count(DISTINCT key) FROM (
-            -- A read of one key names it; of several at one place, lists them (readsByPlace, vault.ts). An entry, or an
-            -- item of its list, that names no key, which only a forged entry is, counts as one key of its own.
-            SELECT coalesce(e.secret_id, CASE WHEN one.type = 'object' AND json_type(one.value, '$.secretId') = 'text' THEN json_extract(one.value, '$.secretId') END, 'entry:' || e.seq) AS key
-            FROM audit_log e
-            LEFT JOIN json_each(CASE WHEN e.secret_id IS NULL AND json_type(e.metadata, '$.secrets') = 'array' THEN e.metadata END, '$.secrets') AS one
-            WHERE e.author = 'vault' AND e.actor = ${released.principal} AND e.action = 'secret.read' AND e.decision = 'allow'
-              AND e.occurred_at > ${NOW} + ${released.clockOffsetMs} - ${released.windowMs}
-            UNION ALL SELECT value FROM json_each(${JSON.stringify(released.keys)})
+          -- The keys released within the window, but those asked for, up to one past the cap (snapshot.postgres.ts).
+          SELECT count(*) FROM (
+            SELECT 1 FROM vault_releases
+            WHERE principal = ${released.principal} AND released_at > ${NOW} + ${released.clockOffsetMs} - ${released.windowMs}
+              AND key NOT IN (SELECT value FROM json_each(${JSON.stringify(released.keys)}))
+            LIMIT ${released.cap + 1}
           )
-        )`}
+        ) + (SELECT count(DISTINCT value) FROM json_each(${JSON.stringify(released.keys)}))`}
     ) AS snapshot`;
 }

package/src/snapshot.ts

@@ -1,6 +1,6 @@
 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';
 
@@ -49,7 +49,9 @@ export type Snapshot = {
   /**
    * 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.
+   * again, or asked for again, counts once. Those released before are
+   * counted up to one past `asked.released.cap`, which is enough to say
+   * whether the read goes past it.
    */
   released: number;
   /** The log's head, locked, with the last entry and the newest `key.rotate`; null unless asked, or held by another. */
@@ -74,11 +76,19 @@ export type Asked = {
   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.
+   * on by `clockOffsetMs` as the vault's is, with `keys`, secret ids, besides;
+   * read from `vault_releases`, which the database keeps from the log, up to
+   * `cap` + 1 of them.
    */
-  released?: { principal: string; keys: readonly string[]; windowMs: number; clockOffsetMs: number };
+  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. */
@@ -90,7 +100,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`).

package/src/store.ts

@@ -2,9 +2,11 @@ import { EVERYWHERE, ownsInstance, type InstanceRole, type Scope } from '@coffre
 import type { Author, StoredEntry } from '@coffre/core/audit';
 import { ACCESS_ACTIONS, type SecretRef, type WrappedKey } from '@coffre/core/vault';
 import { prepared, tablesOf, type Queryable, type Transaction } from '@coffre/db';
-import { clockMillis, engineOf, forUpdate, tombstone, truth } from '@coffre/db/dialect';
+import { changedRows, clockMillis, engineOf, forUpdate, rowsOf, tombstone, truth } from '@coffre/db/dialect';
 import { readGrants, roleColumns, storedRole, type GrantRow } from '@coffre/db/grants';
 import { entryColumns, withinBytes } from '@coffre/db/log';
+
+import { MAX_BULK_WINDOW_MINUTES } from './config.ts';
 import { and, asc, count, desc, eq, gt, gte, inArray, isNotNull, isNull, like, lt, lte, or, sql, type SQL, type SQLWrapper } from 'drizzle-orm';
 
 /**
@@ -67,6 +69,33 @@ export async function boundLockWaits(tx: Transaction, ms: number, statements = f
     : sql.raw(`SET LOCAL lock_timeout = ${bound}`));
 }
 
+/**
+ * How long a release is kept: the longest bulk limit window
+ * (`MAX_BULK_WINDOW_MINUTES`, a day), and an hour, a margin for the
+ * database's clock stepping back between a prune and a later count, which
+ * is seconds. Migration 0021's `prune_vault_releases` holds the same, a day
+ * and an hour, in its own SQL: a longer window takes a migration too.
+ */
+export const RELEASES_KEPT_MS = MAX_BULK_WINDOW_MINUTES * 60_000 + 3_600_000;
+
+/**
+ * Delete up to `atMost` rows of `vault_releases` released over
+ * `RELEASES_KEPT_MS` before the database's clock: what no bulk count can
+ * read again. On Postgres the vault's login deletes no row itself, and asks
+ * `prune_vault_releases`, which deletes only those (migration 0021). How
+ * many went.
+ */
+export async function pruneReleases(db: Queryable, atMost: number): Promise<number> {
+  if (engineOf(db) === 'postgres') {
+    const [row] = await rowsOf<{ pruned: number }>(db, sql`SELECT prune_vault_releases(${atMost}::int) AS pruned`);
+    return row!.pruned;
+  }
+  const { vaultReleases } = tablesOf(db);
+  const old = db.select({ principal: vaultReleases.principal, key: vaultReleases.key }).from(vaultReleases)
+    .where(lt(vaultReleases.releasedAt, sql`${clockMillis(db)} - ${RELEASES_KEPT_MS}`)).limit(atMost);
+  return changedRows(await db.delete(vaultReleases).where(sql`(${vaultReleases.principal}, ${vaultReleases.key}) IN ${old}`));
+}
+
 /** The database's clock, now. */
 export async function now(db: Queryable): Promise<number> {
   const [{ at }] = await clock(db);

package/src/vault.ts

@@ -91,6 +91,9 @@ import {
   type Settings,
   type Through,
   type UnwrapInput,
+  USE_METADATA_LENGTH,
+  type Unwrapped,
+  type UseRecord,
   type Wrapped,
   type Vault,
   type Via,
@@ -101,7 +104,7 @@ import {
 import type { Database, Queryable, Transaction } from '@coffre/db';
 import { isUnavailable, isUniqueViolation, SNAPSHOT } from '@coffre/db/dialect';
 import { everyProjectConversion, newestAccess, reportStands } from '@coffre/db/grants';
-import { appendEntries, lockLogHead, missingEntry, newestAuthentic, type Appended, type Authenticity, type Newest, type NewEntry } from '@coffre/db/log';
+import { appendEntries, lockLogHead, lockLogHeadQueued, missingEntry, newestAuthentic, type Appended, type Authenticity, type Newest, type NewEntry } from '@coffre/db/log';
 
 import { signer, type Signer } from './checkpoint.ts';
 import { keyRefusals, placeIn, referenceRefusal, refuses, sensitiveRefusals, useOnlyRefusals, type SecretPlace } from './decide.ts';
@@ -212,6 +215,46 @@ const LOCK_TIMEOUT_MS = 15_000;
  */
 const READ_LOCK_TIMEOUT_MS = 3_000;
 
+/**
+ * How long a whole read call may take, from its start to its answer, its
+ * refusal's entries, the record of a vault key's check and, with a key
+ * service, its intent and its own budget (added) included: each transaction's waits are bounded by what is left of it, and
+ * past it the call fails as unavailable (`Overdue`) rather than start
+ * another. So a caller hears within it, ok or 503, never tens of seconds later.
+ */
+export const READ_DEADLINE_MS = 5_000;
+
+/**
+ * How many reads may wait for the log's head at once, through all of the
+ * vault's connections; the next is refused at once, as unavailable, holding
+ * no connection while it waits (`lockLogHeadQueued`). A read holds the head
+ * for a few round trips, about 150 ms through Hyperdrive, so this many
+ * clear within a read's bound (2.4 s of its 3), and no more than this many
+ * of the pool's connections wait. A burst of 50 reads at a 2-vCPU database
+ * a 30 ms round trip away: 17 read within 2.2 s, 33 refused at once.
+ */
+export const READ_HEAD_WAITERS = 16;
+
+/** How many releases a checkpoint prunes at most: one short statement, a few each scheduled run. */
+const RELEASES_PRUNED = 10_000;
+
+/** A read's call past its deadline (`READ_DEADLINE_MS`): unavailable, as a statement past its bound (57014) is. */
+class Overdue extends Error {
+  readonly code = '57014';
+  constructor() {
+    super('this read took longer than it may: ask again shortly');
+    this.name = 'Overdue';
+  }
+}
+
+/** The bound of a transaction of a call due at `deadline`: `ms`, or what is left of the call, if less. */
+function within(deadline: number | undefined, ms: number): number {
+  if (deadline === undefined) return ms;
+  const left = deadline - Date.now();
+  if (left <= 0) throw new Overdue();
+  return Math.min(ms, left);
+}
+
 /** A member: `user:<email>` or `token:<name>`. */
 const PRINCIPAL = /^(user|token):[^\s:][^\s]*$/;
 
@@ -406,7 +449,12 @@ type Reads = Pick<Asked, 'environments' | 'references'> & { released?: { princip
  * is what it reads besides its members, and `reads` says it changes none
  * of them (`#decide`).
  */
-type How = { late?: boolean; asked?: Reads; reads?: boolean };
+/**
+ * How a decision is made. `deadline`, a read's (`reads`): when its whole
+ * call must have answered, every wait in every transaction it takes
+ * included (`READ_DEADLINE_MS`).
+ */
+type How = { late?: boolean; asked?: Reads; reads?: boolean; deadline?: number };
 
 /** The actions of the entries the vault writes about keys. */
 type KeyAction = 'secret.read' | 'key.wrap' | 'key.rewrap';
@@ -492,13 +540,15 @@ class VaultService implements Vault {
   }
 
   /** What a decision about `principals` reads, and `asked` besides, in one statement: under the head when `head` is set. */
-  #snapshot(tx: Transaction, principals: readonly string[], asked: Reads, head: boolean): Promise<Snapshot> {
+  #snapshot(tx: Transaction, principals: readonly string[], asked: Reads, head: boolean, reading = false): Promise<Snapshot> {
     const { released, ...rest } = asked;
     return snapshot(tx, {
       ...rest,
       principals,
       head,
-      ...(released === undefined ? {} : { released: { ...released, windowMs: this.#config.bulkLimit.windowMs, clockOffsetMs: this.#prepared.options.clockOffset() } }),
+      // A read waits for the head in one of a few places in line, or is refused at once.
+      ...(reading ? { waiters: READ_HEAD_WAITERS } : {}),
+      ...(released === undefined ? {} : { released: { ...released, windowMs: this.#config.bulkLimit.windowMs, clockOffsetMs: this.#prepared.options.clockOffset(), cap: this.#config.bulkLimit.count } }),
     });
   }
 
@@ -525,9 +575,11 @@ class VaultService implements Vault {
   /** `#decide`, once the vault is settled. */
   async #decideNow<T>(principals: readonly string[], decide: (d: Decision) => Promise<T>, how: How = {}): Promise<Outcome<T>> {
     const reports: NewEntry[] = [];
+    // A read's call is due from its first decision, unless its caller set when.
+    const due = how.reads === true ? { ...how, deadline: how.deadline ?? Date.now() + READ_DEADLINE_MS } : how;
     for (let attempt = 1; ; attempt += 1) {
       try {
-        return await this.#decideOnce(principals, decide, reports, how);
+        return await this.#decideOnce(principals, decide, reports, due);
       } catch (error) {
         // A member who had no row when this decision locked theirs, and has
         // one now: another decision admitted them meanwhile. Again, with it.
@@ -537,13 +589,13 @@ class VaultService implements Vault {
     }
   }
 
-  async #decideOnce<T>(principals: readonly string[], decide: (d: Decision) => Promise<T>, reports: NewEntry[], { late = false, asked = {}, reads: shared = false }: How): Promise<Outcome<T>> {
+  async #decideOnce<T>(principals: readonly string[], decide: (d: Decision) => Promise<T>, reports: NewEntry[], { late = false, asked = {}, reads: shared = false, deadline }: How): Promise<Outcome<T>> {
     try {
       const result = await this.#db.transaction(async (tx) => {
-        await store.boundLockWaits(tx, shared ? READ_LOCK_TIMEOUT_MS : LOCK_TIMEOUT_MS, shared);
+        await store.boundLockWaits(tx, shared ? within(deadline, READ_LOCK_TIMEOUT_MS) : LOCK_TIMEOUT_MS, shared);
         const members = principals.length === 0 ? new Map<string, Member>() : await store.lockMembers(tx, principals, shared);
         // Then the head, and everything the decision reads, in one statement (`snapshot` says why it holds).
-        const reads = await this.#snapshot(tx, principals, asked, !late);
+        const reads = await this.#snapshot(tx, principals, asked, !late, shared);
         const d: Decision = {
           tx, members, at: this.#at(reads), reads, log: [], writes: [], touched: new Set(), grants: new Map(), reports, after: [], underLock: [],
         };
@@ -577,9 +629,12 @@ class VaultService implements Vault {
       if (!(error instanceof Refused || error instanceof Outage)) throw error;
       const entries = [...reports, ...readsByPlace(error.entries)];
       if (entries.length > 0) {
-        // A refusal's entries are written whatever the decision's bound: it answers only once they are.
+        // A refusal's entries are written whatever the decision's bound: it answers only once they are. A read's, within
+        // its call's deadline: past it, the call fails as unavailable, having released nothing.
         await this.#db.transaction(async (tx) => {
-          await store.boundLockWaits(tx, LOCK_TIMEOUT_MS);
+          await store.boundLockWaits(tx, shared ? within(deadline, READ_LOCK_TIMEOUT_MS) : LOCK_TIMEOUT_MS, shared);
+          // In one of the head's places in line, as the read's decision waited, or refused at once.
+          if (shared) await lockLogHeadQueued(tx, READ_HEAD_WAITERS);
           await this.#append(tx, entries);
         });
       }
@@ -928,8 +983,9 @@ class VaultService implements Vault {
 
   // Raw DEKs are cleared on every path. JSON and base64 leave strings that
   // cannot be wiped, so this is best-effort memory hygiene.
-  async unwrap(input: UnwrapInput): Promise<Outcome<{ keys: string[]; accessRevision?: string }>> {
+  async unwrap(input: UnwrapInput): Promise<Outcome<Unwrapped>> {
     const { principal } = input;
+    const use = input.use === undefined ? null : useEntry(principal, input, input.use);
     validateText(input.purpose);
     if (input.keepsSensitive !== undefined && typeof input.keepsSensitive !== 'boolean') throw new Error('keepsSensitive is true, false or absent');
     if (input.accessRevision !== undefined && typeof input.accessRevision !== 'string') throw new Error('accessRevision names an answer of access, or is absent');
@@ -975,6 +1031,17 @@ class VaultService implements Vault {
     if (throughOk.includes(false)) {
       return this.#refuseVersions(principal, 'bad_claim', items.map((item) => entry(item.secret, 'deny', 'bad_claim')), { asked: input.accessRevision });
     }
+    // The app's record of a use names where the read was, which the vault vouches for once it appends it: the place an
+    // item was read at, the fork it is read in, else a reference's holder, else its own, with its project. Another is
+    // a claim the read does not bear out, refused and logged as one; no use is appended.
+    if (use !== null && (use.environmentId !== null || use.projectId !== null)) {
+      const named = items.some((item, i) => {
+        const fork = throughs[i] === null ? undefined : forks.get(throughs[i]!);
+        const place = fork === undefined ? sealed[i]?.holder ?? item.secret : { projectId: fork.projectId, environmentId: throughs[i]! };
+        return (use.environmentId === null || place.environmentId === use.environmentId) && (use.projectId === null || place.projectId === use.projectId);
+      });
+      if (!named) return this.#refuseVersions(principal, 'bad_claim', items.map((item) => entry(item.secret, 'deny', 'bad_claim')), { asked: input.accessRevision });
+    }
     const ends = sealed.flatMap((seal) => (seal === null ? [] : [seal.seq]));
     const remote = items.some(({ wrapped }) => this.#remote(this.#config.keks.providerOf(wrapped)));
     return this.#keys(
@@ -993,6 +1060,7 @@ class VaultService implements Vault {
         remote,
         entry,
         input,
+        ...(use === null ? {} : { also: [use] }),
       },
       (contextOf) =>
         items.map(({ secret, wrapped }) => async (operation: KeyOperation) => {
@@ -1009,6 +1077,8 @@ class VaultService implements Vault {
         }),
         // Named back: the read was decided on that answer, which this vault checked.
         ...(input.accessRevision === undefined ? {} : { accessRevision: input.accessRevision }),
+        // And the use, appended with the read: the app has nothing left to append.
+        ...(use === null ? {} : { used: true as const }),
       }),
     );
   }
@@ -1224,6 +1294,8 @@ class VaultService implements Vault {
       viaReference?: readonly boolean[];
       remote: boolean;
       entry: (secret: SecretRef, decision: 'allow' | 'deny', code: string | null) => NewEntry;
+      /** Entries appended with the release, after its own, only once the keys are released: the app's record of a use. */
+      also?: readonly NewEntry[];
       input: Correlation & Through & { purpose?: string; keepsSensitive?: boolean; accessRevision?: string };
     },
     /**
@@ -1236,11 +1308,14 @@ class VaultService implements Vault {
   ): Promise<Outcome<R>> {
     const { action, principal, secrets, entry } = call;
     for (const secret of secrets) entry(secret, 'allow', null);
-    const wrongKek = await this.#kekMismatch();
+    // One deadline for the call: the record of the KEK's check, the decisions, the intent's and the keys', and, with a
+    // key service, its own budget besides, spent from it too.
+    const deadline = Date.now() + READ_DEADLINE_MS + (call.remote ? this.#prepared.options.keyBudgetMs : 0);
+    const wrongKek = await this.#kekMismatch(deadline);
     if (wrongKek !== null) {
       return this.#decide([], async () => {
         throw new Refused(refusal('wrong_kek', wrongKek), secrets.map((secret) => entry(secret, 'deny', 'wrong_kek')));
-      });
+      }, { reads: true, deadline });
     }
     // Each personal config's owner, hashed, by environment, as the decision read them: what its keys' contexts bind.
     const owners = new Map<string, string>();
@@ -1319,7 +1394,7 @@ class VaultService implements Vault {
           }),
         }], [], d.reads);
         return { seq: appended.seqStart };
-      }, { asked: reads, reads: true });
+      }, { asked: reads, reads: true, deadline });
       if (!intent.ok) return intent;
       intentSeq = intent.seq;
     }
@@ -1355,7 +1430,7 @@ class VaultService implements Vault {
           throw new Refused(refusal(first, MESSAGES[first]), secrets.map((secret, item) => outcomeEntry(secret, item, 'deny', codes[item] ?? first)));
         });
       }
-      const { outcomes, expired } = await settle(operations((secret) => context(secret, owners.get(secret.environmentId))), this.#prepared.options.keyBudgetMs);
+      const { outcomes, expired } = await settle(operations((secret) => context(secret, owners.get(secret.environmentId))), within(deadline, this.#prepared.options.keyBudgetMs));
       const done = outcomes.flatMap((outcome) => (outcome.ok ? [outcome.value] : []));
       try {
         const entries = () => secrets.map((secret, i) =>
@@ -1381,7 +1456,7 @@ class VaultService implements Vault {
           // A read through a reference: its holder's place too, which a deletion may have taken.
           // And as the policy is now, under the head every change to it takes: an environment protected, or a role narrowed,
           // since the check above is seen here, and nothing it refuses now is released. All of it read again, holding the head.
-          d.reads = await this.#snapshot(d.tx, [principal], reads, true);
+          d.reads = await this.#snapshot(d.tx, [principal], reads, true, true);
           d.at = this.#at(d.reads);
           await decided(d);
           const places = secrets.flatMap((secret, i) => [secret, call.places?.[i] ?? secret]);
@@ -1390,7 +1465,7 @@ class VaultService implements Vault {
           }
         }
         const released = secrets.map((secret, i) => outcomeEntry(secret, i, 'allow', null));
-        d.log.push(...released);
+        d.log.push(...released, ...(call.also ?? []));
         const answer = result(done);
         // A wrap's answer names its entries, which the app's writes refer to.
         if (action !== 'secret.read') d.after.push((seqOf) => Object.assign(answer as object, { seqs: released.map(seqOf) }));
@@ -1398,7 +1473,7 @@ class VaultService implements Vault {
       } finally {
         for (const value of done) value.wipe();
       }
-    }, { late, asked: reads, reads: true });
+    }, { late, asked: reads, reads: true, deadline });
   }
 
   /**
@@ -2404,10 +2479,10 @@ class VaultService implements Vault {
    * service that cannot answer leaves it undecided: the error is thrown,
    * and the next call asks again.
    */
-  async #kekMismatch(): Promise<string | null> {
+  async #kekMismatch(deadline?: number): Promise<string | null> {
     const prepared = this.#prepared;
     if (!prepared.kekChecked) {
-      const wrong = await this.#checkKeks();
+      const wrong = await this.#checkKeks(deadline);
       if (!prepared.kekChecked) {
         prepared.wrongKek = wrong;
         prepared.kekChecked = true;
@@ -2422,14 +2497,16 @@ class VaultService implements Vault {
    * keys it wrapped, if there are any; then its check value is recorded.
    * A KEK that opens neither is not the one that wrapped the data.
    */
-  async #checkKeks(): Promise<string | null> {
+  async #checkKeks(deadline?: number): Promise<string | null> {
     // A vault that may not write cannot record a check either; why it may not is the answer.
     const superseded = await this.#settled();
     if (superseded !== null) return superseded;
     const checks = await this.#checkValues(this.#db);
     const budget = this.#prepared.options.keyBudgetMs;
     for (const kek of this.#config.keks.all) {
-      const operation = { deadline: Date.now() + budget, signal: AbortSignal.timeout(budget) };
+      // A read's, within what is left of its deadline.
+      const spend = within(deadline, budget);
+      const operation = { deadline: Date.now() + spend, signal: AbortSignal.timeout(spend) };
       const opens = async (wrapped: WrappedDek, context: SecretContext, expected?: Buffer) => {
         try {
           const key = await kek.unwrap(wrapped, context, operation);
@@ -2460,6 +2537,8 @@ class VaultService implements Vault {
       // The key it opened, if any, is in the log, as every key the vault opens is. Another call that
       // checked at the same time may have recorded one first: under the log's lock, the first stays.
       await this.#db.transaction(async (tx) => {
+        // Once a process, by its first key operation: a read's waits as the read's, within its deadline.
+        await store.boundLockWaits(tx, within(deadline, READ_LOCK_TIMEOUT_MS), true);
         await lockLogHead(tx);
         if ((await this.#checkValues(tx)).has(`${kek.provider}:${kek.keyId}`)) return;
         await this.#append(tx, [
@@ -2578,9 +2657,9 @@ class VaultService implements Vault {
     const { walks } = this.#prepared.options;
     const found: NewEntry[] = [];
     // The newest checkpoint entry, signed or refused, as this call's snapshot found it.
-    let seen: bigint | null = null;
+    let seen: StoredEntry | undefined;
     const resumed = await this.#db.transaction(async (tx) => {
-      seen = (await store.newestCheckpointEntry(tx))?.seq ?? null;
+      seen = await store.newestCheckpointEntry(tx);
       await this.#sweep(tx, found);
       const from = await this.#resume(tx, 'newest');
       if (!from.ok) return from;
@@ -2607,7 +2686,7 @@ class VaultService implements Vault {
         stalled = `the rehash of the past did not run, and goes on where it was next time: ${(error as Error).message}`;
       }
     }
-    return this.#decide([], async (d) => {
+    const decided = await this.#decide([], async (d) => {
       for (const entry of found) if (!d.reports.includes(entry)) d.reports.push(entry);
       // Checkpoints one at a time, each against the one before.
       const head = await lockLogHead(d.tx);
@@ -2625,10 +2704,17 @@ class VaultService implements Vault {
       // Another call checkpointed, or refused to, since this one's snapshot, or this one's rehash of the past
       // could not run: what it would sign over is not what it checked. A refusal for a broken log stands,
       // and a checkpoint signed meanwhile is the newest prefix; the next call starts from them.
-      if (stalled !== null || ((await store.newestCheckpointEntry(d.tx))?.seq ?? null) !== seen) {
+      if (stalled !== null || ((await store.newestCheckpointEntry(d.tx))?.seq ?? null) !== (seen?.seq ?? null)) {
         const standing = await this.#standingRefusal(d.tx);
         if (standing !== null) throw refused('log_broken', standing);
         if (stalled === null && newest !== null) return { checkpoint: signedPart(newest) };
+      } else if (seen?.decision === 'deny' && walked.ok) {
+        // A refusal for a broken log stands since this call's snapshot, of an entry before where its walk began, which
+        // it never read: that entry again, as the walk checks each, before anything is signed over it. Still broken,
+        // the refusal stands; whole again, the signature clears it (T104).
+        const standing = await this.#standingRefusal(d.tx);
+        const named = typeof standing?.failedAtSeq === 'number' ? BigInt(standing.failedAtSeq) : null;
+        if (named !== null && named <= walked.from.at.seq && !(await this.#entryHolds(d.tx, named))) throw refused('log_broken', standing!);
       }
       // Nothing since the last one, which signed every entry before its own: it is still the newest prefix.
       if (newest !== null && latest!.seq === head.nextSeq - 1n && latest!.relatedSeq === latest!.seq - 1n) return { checkpoint: signedPart(newest) };
@@ -2676,6 +2762,15 @@ class VaultService implements Vault {
       d.log.push({ actor: SCHEDULER, action: CHECKPOINT, decision: 'allow', relatedSeq: at.seq, metadata: JSON.stringify(kept) });
       return stalled === null ? { checkpoint } : { checkpoint, warning: stalled };
     });
+    // Then the bulk count's upkeep, which no read waits on, after a checkpoint signed, never instead of a refusal: the
+    // releases no window can count again, kept a day and an hour (`RELEASES_KEPT_MS`), longer than any window, up to
+    // `RELEASES_PRUNED` of them, in one statement of its own, holding no lock any read takes but the rows it deletes,
+    // and none an append holds. What is kept is the database's to say, not the caller's: no login forgets a release a
+    // window counts. A failure leaves it to the next checkpoint, and says so.
+    if (!decided.ok) return decided;
+    const pruned = await store.pruneReleases(this.#db, RELEASES_PRUNED).then(() => null, (error: Error) => `the releases the bulk limit counts were not pruned, and the next checkpoint tries again: ${error.message}`);
+    if (pruned === null) return decided;
+    return { ...decided, warning: decided.warning === undefined ? pruned : `${decided.warning}; ${pruned}` };
   }
 
   /**
@@ -2722,6 +2817,22 @@ class VaultService implements Vault {
     return { ok: true, next: null };
   }
 
+  /**
+   * Whether entry `seq` is as the walk checks each: there, its hash its
+   * own, linked to the entry before, and the vault's under its MAC; and the
+   * entry after it, if any, linked to it, for a refusal can name either side
+   * of a broken link (`forward`, at the end of a batch).
+   */
+  async #entryHolds(db: Queryable, seq: bigint): Promise<boolean> {
+    const found = await store.entriesAt(db, seq === 0n ? [seq, seq + 1n] : [seq - 1n, seq, seq + 1n]);
+    const entry = found.get(seq);
+    const before = seq === 0n ? { hash: GENESIS_HASH } : found.get(seq - 1n);
+    if (entry === undefined || before === undefined) return false;
+    const after = found.get(seq + 1n);
+    if (after !== undefined && !after.prevHash.equals(entry.hash)) return false;
+    return verifyEntries([entry], { keys: this.#keysFor(entry), chainOnly: ['app'], startSeq: seq, startPrevHash: before.hash }).ok;
+  }
+
   /**
    * The newest refusal for a broken log since the newest checkpoint was
    * signed, by the vault's MAC, as it said: it stands, for every
@@ -3065,6 +3176,45 @@ function validateText(value: string): void {
 
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 
+/**
+ * The app's `credential.use` entry, as the vault appends it beside a read
+ * (`UnwrapInput.use`): what the app wrote, checked to be what an entry
+ * holds, in its reader's name. The app wrote it under the head itself
+ * before 0.14.5; it describes the read, and decides nothing.
+ */
+function useEntry(principal: string, correlation: Correlation, use: UseRecord): NewEntry {
+  const id = (value: unknown, name: string) => {
+    if (value !== null && (typeof value !== 'string' || !UUID.test(value))) throw new Error(`a use's ${name} must be a lowercase UUID or null`);
+    return value;
+  };
+  // The bound first: nothing past it is read.
+  if (typeof use.metadata !== 'string' || use.metadata.length > USE_METADATA_LENGTH) {
+    throw new Error(`a use's metadata must be a JSON object of at most ${USE_METADATA_LENGTH} characters`);
+  }
+  if (use.sourceIp !== null) validateText(use.sourceIp);
+  validateText(use.metadata);
+  let metadata: unknown;
+  try {
+    metadata = JSON.parse(use.metadata);
+  } catch {
+    metadata = undefined;
+  }
+  if (typeof metadata !== 'object' || metadata === null || Array.isArray(metadata)) {
+    throw new Error(`a use's metadata must be a JSON object of at most ${USE_METADATA_LENGTH} characters`);
+  }
+  return {
+    actor: principal,
+    action: 'credential.use',
+    decision: 'allow',
+    projectId: id(use.projectId, 'projectId'),
+    environmentId: id(use.environmentId, 'environmentId'),
+    operationId: correlation.operationId ?? null,
+    requestId: correlation.requestId ?? null,
+    sourceIp: use.sourceIp,
+    metadata: use.metadata,
+  };
+}
+
 /** The caller's ids go into the log as they are: a request id is text, an operation id a lowercase UUID. */
 function validateCorrelation(input: Correlation): void {
   if (input.requestId != null) validateText(input.requestId);