@coffre/vault 0.14.4 → 0.15.0

package/dist/cloudflare.js

@@ -1,8 +1,638 @@
-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-BBdXsny3.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-DheG92EM.js";
+import { _ as Unsealed, b as sealingOf, c as openLogCheckpointer, d as dayOf, f as Projector, g as TICK_BOUND_MS, i as logStore, l as reasonOf, m as SEAL_WAIT_MS, n as prepareVault, p as Fence, r as verifierKeys, s as daysAround, t as openVault, u as upkeep, v as WITNESS_DEADLINE_MS, x as within, y as heldIn } from "./vault-kmtojYnW.js";
 import { createDatabase } from "@coffre/db";
 import { HyperdrivePool, postgres } from "@coffre/db/hyperdrive";
 import { WorkerEntrypoint } from "cloudflare:workers";
+import { decodePair, encodePair, noteSigner, openPair, pairVerifiers, parseCheckpoint, splitNote, witnessPair } from "@coffre/core/merkle";
+//#region src/checkpointer-workers.ts
+/**
+* The signer's memory in the object's storage: one key, the pair's record,
+* durable before `remember` returns. The output gate holds a Response and a
+* new connection until the write is, but not a query on a connection
+* already open, as the database write is: `sync()` makes RememberFirst hold
+* without leaning on it (Fable's review).
+*/
+function durableMemory(storage) {
+	return {
+		last: async () => await storage.get("pair") ?? null,
+		async remember(record) {
+			await storage.put("pair", record);
+			await storage.sync();
+		}
+	};
+}
+/** How long alarms are kept. */
+const ALARMS_KEPT_MS = 2592e6;
+/**
+* How long the object waits on an open, which reads the newest pair and the trees' edges, and on the next days of
+* uses made without it (T169): as long as a tick.
+*/
+const OPEN_BOUND_MS = TICK_BOUND_MS;
+/** How long it waits on the log's upkeep after a tick: retention drops a day's partition and its tiles, hourly. */
+const UPKEEP_BOUND_MS = 6e4;
+/** How long the vault waits on the object for anything but a seal: a start, its status, the pair it remembers. */
+const ASK_BOUND_MS = 2e3;
+/** How long the vault waits on the object for a seal: its own bound, and the witnesses', and a second more. */
+const SEAL_ASK_BOUND_MS = SEAL_WAIT_MS + WITNESS_DEADLINE_MS + 1e3;
+/** An alarm's key: its time, then random bytes, so that two at one millisecond never share one, evicted or not. */
+const alarmKey = (at, suffix = "") => `alarm:${String(at).padStart(16, "0")}:${suffix}`;
+/** The Durable Object class the deployment binds, configured from `env` as the vault is. */
+function checkpointerObject(settings) {
+	return class CoffreCheckpointer {
+		#state;
+		#env;
+		#checkpointer = null;
+		#pool = null;
+		/** The log's upkeep after each tick (log-checkpointer.ts), with the checkpointer it was opened with. */
+		#upkeep = null;
+		/** Whether this object is the reads' projector, as its storage says (`startProjector`); asked once. */
+		#projects = null;
+		/** The projector, on a connection of its own for as long as the object lives, as the checkpointer's. */
+		#projector = null;
+		/** The day the next days of uses were last made for without the checkpointer (`#makeDays`), when it last tried, and its failure. */
+		#daysFor = null;
+		#daysTried = -Infinity;
+		#daysFailed = null;
+		/** Whether the upkeep after a tick that held runs now (`alarm`), which readiness counts as the tick's time. */
+		#upkeeping = false;
+		/**
+		* The last tick as readiness reads it: during the upkeep after it, as if it had just ended. What stood since, a seal's
+		* tick that stalled or was refused meanwhile, readiness reads from the checkpointer itself (`standing`).
+		*/
+		#lastSeen() {
+			const last = this.#ticks.at(-1) ?? null;
+			return last === null || !this.#upkeeping ? last : {
+				at: Date.now(),
+				failures: last.failures
+			};
+		}
+		/** The last ticks, newest last, with their wall time in the object: `status`. */
+		#ticks = [];
+		constructor(state, env) {
+			this.#state = state;
+			this.#env = env;
+		}
+		/** The checkpointer, opened once, every other request held meanwhile, so that two never open it side by side. */
+		/**
+		* Null when it cannot be opened: `open()` refuses the gravest states the log has (entries the signer sealed lost,
+		* another pair at its place, time run back), and each is an alarm, kept once while it stands. Never thrown from
+		* inside the gate, which would reset the object.
+		*/
+		async #open() {
+			if (this.#checkpointer !== null) return this.#checkpointer;
+			return this.#state.blockConcurrencyWhile(async () => {
+				if (this.#checkpointer !== null) return this.#checkpointer;
+				let pool = null;
+				const fence = new Fence();
+				try {
+					const s = await settings(this.#env);
+					const opening = new HyperdrivePool(s.hyperdrive.connectionString, { closeIdleMs: s.closeIdleMs ?? 1e4 });
+					pool = opening;
+					const store = logStore(createDatabase(pool));
+					const checkpointer = await within(openLogCheckpointer({
+						store,
+						seed: s.seed,
+						memory: durableMemory(this.#state.storage),
+						witnesses: s.witnesses,
+						record: (alarm) => this.#record(alarm),
+						fence,
+						...s.tickBoundMs === void 0 ? {} : { tickBoundMs: s.tickBoundMs }
+					}), s.tickBoundMs ?? OPEN_BOUND_MS, "the open", () => {
+						fence.close("its open stalled");
+						opening.destroy();
+					});
+					this.#checkpointer = checkpointer;
+					this.#upkeep = upkeep(checkpointer, fence.store(store), {
+						keepDays: s.retainDays ?? null,
+						seed: s.seed,
+						alert: (message) => {
+							console.warn(`coffre audit: ${message}`);
+							this.#record({
+								at: Date.now(),
+								message
+							}).catch((error) => console.warn(`coffre audit: the alarm could not be kept: ${error.message}`));
+						}
+					});
+				} catch (error) {
+					await fence.close("its open failed");
+					pool?.destroy();
+					await this.#failure(`the checkpointer cannot open: ${reasonOf(error)}`);
+					return null;
+				}
+				this.#pool = pool;
+				return this.#checkpointer;
+			});
+		}
+		/** The failure that stands, alarmed once: a refused open, a tick that threw. */
+		#failed = null;
+		async #failure(message) {
+			if (message === this.#failed) return;
+			this.#failed = message;
+			console.warn(`coffre audit: ${message}`);
+			await this.#record({
+				at: Date.now(),
+				message
+			}).catch((error) => console.warn(`coffre audit: the alarm could not be kept: ${error.message}`));
+		}
+		/**
+		* Nothing else delivered meanwhile, and the old checkpointer closed, fenced, its tick in flight ended or stalled,
+		* before the next request may open another: a change still waiting on the old one can tick it no more, so two
+		* never sign at once. Its connection is cut first, so that what it still awaits fails now rather than whenever the
+		* database answers (T169); a statement it had sent may still land, which the fence's rules allow.
+		*/
+		async #reset() {
+			await this.#state.blockConcurrencyWhile(async () => {
+				const [old, pool] = [this.#checkpointer, this.#pool];
+				this.#checkpointer = null;
+				this.#pool = null;
+				this.#upkeep = null;
+				pool?.destroy();
+				await old?.close();
+			});
+		}
+		async #record(alarm) {
+			const storage = this.#state.storage;
+			await storage.put(alarmKey(alarm.at, crypto.randomUUID()), alarm.message);
+			const old = await storage.list({
+				prefix: "alarm:",
+				end: alarmKey(alarm.at - ALARMS_KEPT_MS),
+				limit: 128
+			});
+			if (old.size > 0) await storage.delete([...old.keys()]);
+		}
+		/**
+		* The next days of uses, made once a day when the checkpointer cannot open or tick, over a connection of their own:
+		* a use needs its day's partition whatever the audit's state, and making one needs no signer.
+		*/
+		async #makeDays() {
+			const now = Date.now();
+			const today = dayOf(now);
+			if (this.#daysFor === today || now - this.#daysTried < 36e5) return;
+			this.#daysTried = now;
+			let pool = null;
+			try {
+				const s = await settings(this.#env);
+				const making = new HyperdrivePool(s.hyperdrive.connectionString, { closeIdleMs: 1e3 });
+				pool = making;
+				await within(logStore(createDatabase(making)).makeDays(daysAround(now)), s.tickBoundMs ?? OPEN_BOUND_MS, "making them", () => making.destroy());
+				this.#daysFor = today;
+				this.#daysFailed = null;
+			} catch (error) {
+				const message = `the next days of uses were not made: ${reasonOf(error)}`;
+				if (message !== this.#daysFailed) {
+					console.warn(`coffre audit: ${message}`);
+					await this.#record({
+						at: now,
+						message
+					}).catch((e) => console.warn(`coffre audit: the alarm could not be kept: ${e.message}`));
+				}
+				this.#daysFailed = message;
+			} finally {
+				pool?.destroy();
+			}
+		}
+		/**
+		* The projector's run: some steps of `projectReads`, then the next alarm, a tick later, or at once while a run
+		* leaves sealed uses to project. A failure is an alarm, said once while it stands (`Projector`), and the next
+		* tick tries again, on the same connection, which postgres.js opens again when it is lost.
+		*/
+		async #project() {
+			let more = false;
+			try {
+				if (this.#projector === null) {
+					const s = await settings(this.#env);
+					const pool = new HyperdrivePool(s.hyperdrive.connectionString, { closeIdleMs: s.closeIdleMs ?? 1e4 });
+					const store = logStore(createDatabase(pool));
+					this.#projector = new Projector(store, await verifierKeys([s.seed]), (message) => {
+						console.warn(`coffre audit: ${message}`);
+						this.#record({
+							at: Date.now(),
+							message
+						}).catch((error) => console.warn(`coffre audit: the alarm could not be kept: ${error.message}`));
+					});
+				}
+				more = await this.#projector.run();
+			} catch (error) {
+				this.#projector = null;
+				await this.#failure(`the reads' projection cannot open: ${reasonOf(error)}`);
+			} finally {
+				await this.#state.storage.setAlarm(Date.now() + (more ? 0 : 500));
+			}
+		}
+		async #isProjector() {
+			return this.#projects ??= await this.#state.storage.get("role") === "reads";
+		}
+		async alarm() {
+			if (await this.#isProjector()) return this.#project();
+			let more = false;
+			try {
+				const checkpointer = await this.#open();
+				if (checkpointer === null) return await this.#makeDays();
+				const t0 = performance.now();
+				const t = await checkpointer.tick();
+				this.#ticks.push({
+					...t,
+					wallMs: performance.now() - t0,
+					at: Date.now()
+				});
+				if (this.#ticks.length > 64) this.#ticks.shift();
+				this.#failed = null;
+				more = t.more;
+				const pool = this.#pool;
+				if (this.#upkeep !== null && !more) {
+					this.#upkeeping = true;
+					try {
+						await within(this.#upkeep(), UPKEEP_BOUND_MS, "the log's upkeep", () => pool?.destroy());
+					} finally {
+						this.#upkeeping = false;
+						const last = this.#ticks.at(-1);
+						if (last !== void 0) last.at = Date.now();
+					}
+				}
+			} catch (error) {
+				await this.#failure(`a checkpoint failed: ${reasonOf(error)}`);
+				await this.#reset();
+				await this.#makeDays();
+			} finally {
+				await this.#state.storage.setAlarm(Date.now() + (more ? 0 : 500));
+			}
+		}
+		async fetch(request) {
+			try {
+				const call = await request.json();
+				if (call.op === "project") {
+					if (!await this.#isProjector()) {
+						await this.#state.storage.put("role", "reads");
+						this.#projects = true;
+					}
+					if (await this.#state.storage.getAlarm() === null) await this.#state.storage.setAlarm(Date.now() + 500);
+					return Response.json({ ok: true });
+				}
+				if (await this.#isProjector() && call.op !== "alarms") return new Response("the reads' projector seals nothing", { status: 400 });
+				if (call.op === "start") {
+					if (await this.#state.storage.getAlarm() === null) await this.#state.storage.setAlarm(Date.now() + 500);
+					if (await this.#open() === null) return Response.json({ error: this.#failed }, { status: 503 });
+					return Response.json({ ok: true });
+				}
+				if (call.op === "seal") {
+					const checkpointer = await this.#open();
+					if (checkpointer === null) return Response.json({ error: new Unsealed(BigInt(call.number), this.#failed ?? "the checkpointer cannot open").message }, { status: 503 });
+					try {
+						return Response.json(sealedToJson(await checkpointer.sealThrough(BigInt(call.number), call.deadline)));
+					} catch (error) {
+						if (error instanceof Unsealed) return Response.json({ error: error.message }, { status: 503 });
+						throw error;
+					}
+				}
+				if (call.op === "status") {
+					const head = this.#checkpointer?.pair.pair;
+					return Response.json({
+						open: this.#checkpointer !== null,
+						failed: this.#failed,
+						sealing: sealingOf({
+							open: this.#checkpointer !== null,
+							failed: this.#failed ?? this.#checkpointer?.standing ?? null,
+							last: this.#lastSeen()
+						}),
+						upto: head === void 0 ? null : String(head.upto),
+						sizes: head === void 0 ? null : {
+							changes: head.changes.size,
+							uses: head.uses.size
+						},
+						ticks: this.#ticks.map((t) => ({
+							...t,
+							upto: String(t.upto)
+						}))
+					});
+				}
+				if (call.op === "remembered") return Response.json({ held: heldIn(await durableMemory(this.#state.storage).last()) });
+				if (call.op === "alarms") {
+					const alarms = [];
+					let start = alarmKey(call.since ?? 0);
+					let last = null;
+					for (;;) {
+						const page = await this.#state.storage.list({
+							prefix: "alarm:",
+							start,
+							limit: 1e3
+						});
+						for (const [key, message] of page) if (key !== last) alarms.push({
+							at: Number(key.split(":")[1]),
+							message
+						});
+						if (page.size < 1e3) break;
+						last = start = [...page.keys()].at(-1);
+					}
+					return Response.json(alarms);
+				}
+				return new Response("unknown op", { status: 400 });
+			} catch (error) {
+				return Response.json({ error: error.message }, { status: 500 });
+			}
+		}
+	};
+}
+/**
+* Asks the checkpointer's object, as `durableSealThrough(env.CHECKPOINTER)` and `startCheckpointer(env.CHECKPOINTER)`
+* do, for at most `ms` (T169): an object that does not answer, its gate held or its isolate wedged, fails the ask
+* rather than the call that asked.
+*/
+async function ask(namespace, name, call, ms = ASK_BOUND_MS) {
+	if (typeof namespace?.idFromName !== "function") throw new Error("there is no CHECKPOINTER binding: bind the CoffreCheckpointer Durable Object to the vault");
+	const asked = (async () => {
+		const response = await namespace.get(namespace.idFromName(name)).fetch(new Request("https://checkpointer/", {
+			method: "POST",
+			body: JSON.stringify(call)
+		}));
+		return {
+			response,
+			body: await response.json()
+		};
+	})();
+	const { response, body } = await within(asked, ms, "the checkpointer's object");
+	if (!response.ok) throw Object.assign(/* @__PURE__ */ new Error(`the checkpointer failed: ${body.error ?? response.status}`), { status: response.status });
+	return body;
+}
+/**
+* The change path's seam on Workers (plan PR 4): seal through the checkpointer's object. Its 503, or no answer in
+* time, is `Unsealed` (T169): the change is committed and in force, and the app says 503, try again.
+*/
+function durableSealThrough(namespace, name = "checkpointer") {
+	return async (number, deadline) => {
+		let sealed;
+		try {
+			sealed = await ask(namespace, name, {
+				op: "seal",
+				number: String(number),
+				deadline
+			}, SEAL_ASK_BOUND_MS);
+		} catch (error) {
+			if (error.status === void 0) throw new Unsealed(number, `the checkpointer's object did not answer: ${error.message}`, error);
+			throw error;
+		}
+		return sealedFromJson(sealed);
+	};
+}
+/** Starts the object's ticks, once; again is harmless. Throws when it cannot open, its alarm set all the same. */
+async function startCheckpointer(namespace, name = "checkpointer") {
+	await ask(namespace, name, { op: "start" });
+}
+/**
+* Starts the reads' projector (reads.ts, T166): the object of the same class named `name`, which projects from then
+* on, on its own alarm. Again is harmless.
+*/
+async function startProjector(namespace, name = "reads") {
+	await ask(namespace, name, { op: "project" });
+}
+/** The object's head and its last ticks, each with its barrier, write and wall time. */
+function checkpointerStatus(namespace, name = "checkpointer") {
+	return ask(namespace, name, { op: "status" });
+}
+/** Whether the object seals (`Vault.sealing`, T169): its own view, or, if it does not answer within 2 s, that it does not. */
+function durableSealing(namespace, name = "checkpointer") {
+	return async () => {
+		try {
+			return (await checkpointerStatus(namespace, name)).sealing;
+		} catch (error) {
+			return {
+				ok: false,
+				reason: `the checkpointer's object did not answer: ${error.message}`
+			};
+		}
+	};
+}
+/**
+* The pair the signer remembers, where no database writer reaches: what the
+* vault's verifier holds its walks to (`VaultOptions.heldOutside`).
+*/
+function durableHeldOutside(namespace, name = "checkpointer") {
+	return async () => {
+		const { held } = await ask(namespace, name, { op: "remembered" });
+		return held;
+	};
+}
+/** The alarms the object kept since `since` (ms). */
+function checkpointerAlarms(namespace, since = 0, name = "checkpointer") {
+	return ask(namespace, name, {
+		op: "alarms",
+		since
+	});
+}
+function sealedToJson(s) {
+	const p = s.proof;
+	return {
+		notes: s.notes,
+		witnessed: s.witnessed,
+		failures: s.failures,
+		cosigned: s.cosigned,
+		proof: {
+			number: String(p.number),
+			tree: p.tree,
+			index: p.index,
+			size: p.size,
+			leaf: p.leaf.toString("base64"),
+			proof: p.proof.map((h) => h.toString("base64")),
+			notes: p.notes
+		}
+	};
+}
+/** The answer as the object sent it. Its notes are the vault's own, signed in the object: read, not verified again. */
+function sealedFromJson(j) {
+	const read = (note) => parseCheckpoint(splitNote(note).text);
+	const [changes, uses] = [read(j.notes.changes), read(j.notes.uses)];
+	return {
+		pair: {
+			upto: changes.upto,
+			at: changes.at,
+			floor: changes.floor,
+			prev: changes.prev,
+			changes,
+			uses
+		},
+		notes: j.notes,
+		witnessed: j.witnessed,
+		failures: j.failures,
+		cosigned: j.cosigned,
+		proof: {
+			...j.proof,
+			number: BigInt(j.proof.number),
+			leaf: Buffer.from(j.proof.leaf, "base64"),
+			proof: j.proof.proof.map((h) => Buffer.from(h, "base64"))
+		}
+	};
+}
+//#endregion
+//#region src/witness-workers.ts
+/** The witness's Durable Object class. A new name for it is a new witness, which takes the next pair it is sent as given. */
+function witnessObject(settings) {
+	return class CoffreWitness {
+		#state;
+		#env;
+		constructor(state, env) {
+			this.#state = state;
+			this.#env = env;
+		}
+		async fetch(request) {
+			try {
+				const body = request.method === "GET" ? null : await request.json();
+				return await this.#state.blockConcurrencyWhile(() => this.#answer(body));
+			} catch (error) {
+				return Response.json({
+					ok: false,
+					reason: `the witness failed: ${error.message}`
+				}, { status: 500 });
+			}
+		}
+		/** Every failure answered from inside the gate, never thrown out of it, which would reset the object. */
+		async #answer(p) {
+			try {
+				return await this.#answerOr(p);
+			} catch (error) {
+				return Response.json({
+					ok: false,
+					reason: `the witness failed: ${error.message}`
+				}, { status: 500 });
+			}
+		}
+		async #answerOr(p) {
+			const s = await settings(this.#env);
+			const log = await pairVerifiers(s.log);
+			const self = await noteSigner(s.name, Buffer.from(s.key, "base64"));
+			const stored = await this.#state.storage.get("pair");
+			const notes = stored === void 0 ? null : decodePair(stored);
+			const pair = notes === null ? null : await openPair(notes, log);
+			if (stored !== void 0 && pair === null) return Response.json({
+				ok: false,
+				reason: "the pair this witness holds does not open under the log's keys: name a new witness"
+			}, { status: 500 });
+			const held = pair === null ? null : {
+				pair,
+				notes
+			};
+			const sizes = {
+				changes: held?.pair.changes.size ?? 0,
+				uses: held?.pair.uses.size ?? 0
+			};
+			if (p === null) return Response.json({ held: sizes });
+			if (p.from.changes !== sizes.changes || p.from.uses !== sizes.uses) return Response.json({ held: sizes }, { status: 409 });
+			const proofs = {
+				changes: p.proofs.changes.map((h) => Buffer.from(h, "base64")),
+				uses: p.proofs.uses.map((h) => Buffer.from(h, "base64"))
+			};
+			const r = await witnessPair(held, p.notes, proofs, log, self);
+			if (!r.answer.ok) return Response.json(r.answer, { status: 422 });
+			await this.#state.storage.put("pair", encodePair(p.notes));
+			return Response.json(r.answer);
+		}
+	};
+}
+/** The witness's object as the checkpointer's `Witness`: the pair and each tree's proof from the sizes the object holds. */
+function durableWitness(namespace, options = {}) {
+	const name = options.name ?? "witness";
+	let held = null;
+	return {
+		name,
+		async publish(notes, proofs, signal) {
+			if (typeof namespace?.idFromName !== "function") return {
+				ok: false,
+				reason: "there is no WITNESS binding"
+			};
+			const object = namespace.get(namespace.idFromName(name));
+			for (let tries = 0; tries < 2; tries += 1) {
+				if (held === null) {
+					const response = await object.fetch(new Request("https://witness/", {
+						method: "GET",
+						signal
+					}));
+					const body = await response.json().catch(() => ({}));
+					const sizes = sizesIn(body.held);
+					if (!response.ok || sizes === null) return {
+						ok: false,
+						reason: body.reason ?? `the witness answered ${response.status}`
+					};
+					held = sizes;
+				}
+				const from = held;
+				const p = await proofs(from);
+				const body = {
+					notes,
+					from,
+					proofs: {
+						changes: p.changes.map((h) => h.toString("base64")),
+						uses: p.uses.map((h) => h.toString("base64"))
+					}
+				};
+				const response = await object.fetch(new Request("https://witness/", {
+					method: "POST",
+					body: JSON.stringify(body),
+					signal
+				}));
+				const answer = await response.json().catch(() => ({ ok: false }));
+				if (response.status === 409) {
+					held = sizesIn(answer.held);
+					if (held === null) return {
+						ok: false,
+						reason: `the witness answered 409 without sizes it holds`
+					};
+					continue;
+				}
+				if (!answer.ok) return {
+					ok: false,
+					reason: answer.reason ?? `the witness answered ${response.status}`
+				};
+				held = sizesOf(notes);
+				return {
+					ok: true,
+					cosigned: answer.cosigned
+				};
+			}
+			return {
+				ok: false,
+				reason: "the witness kept holding other sizes"
+			};
+		}
+	};
+}
+/** Sizes a witness says it holds, if they are sizes: whole numbers, none below zero. */
+function sizesIn(value) {
+	const sizes = value;
+	const size = (n) => Number.isSafeInteger(n) && n >= 0;
+	return sizes != null && size(sizes.changes) && size(sizes.uses) ? {
+		changes: sizes.changes,
+		uses: sizes.uses
+	} : null;
+}
+/** Each tree's size, read from its note (the checkpointer's own, just signed). */
+const sizesOf = (notes) => ({
+	changes: Number(notes.changes.split("\n")[1]),
+	uses: Number(notes.uses.split("\n")[1])
+});
+/**
+* Each pair it is sent, kept in an R2 bucket under `<prefix><upto, 20 digits>.json`.
+* A place already archived with the same pair is fine (a pair sent again);
+* one archived with another is refused, and said.
+*/
+function r2Archive(bucket, options = {}) {
+	const prefix = options.prefix ?? "audit/";
+	return {
+		name: "r2-archive",
+		async publish(notes) {
+			const upto = notes.changes.split("\n")[3]?.slice(5) ?? "";
+			if (!/^\d{1,19}$/.test(upto)) return {
+				ok: false,
+				reason: "not a checkpoint pair"
+			};
+			const key = `${prefix}${upto.padStart(20, "0")}.json`;
+			const record = encodePair(notes);
+			if (await bucket.put(key, record, { onlyIf: { etagDoesNotMatch: "*" } }).catch(() => null) !== null) return { ok: true };
+			return await (await bucket.get(key))?.text() === record ? { ok: true } : {
+				ok: false,
+				reason: `the archive holds another pair up to ${upto}`
+			};
+		}
+	};
+}
+//#endregion
 //#region src/cloudflare.ts
 /** Set when the Worker's module runs `vault(…)`, before any call comes in. */
 let configure = null;
@@ -12,6 +642,8 @@ let configure = null;
 * would belong to the call that started it (vault.ts, `PreparedVault`).
 */
 const ready = /* @__PURE__ */ new WeakMap();
+/** How long after a start that failed, the checkpointer's object out of reach, the next call tries again. */
+const START_AGAIN_MS = 1e4;
 /**
 * What the app's `VAULT` service binding calls. Each call gets a database of
 * its own, one client that its queries take turns on, since a Worker's
@@ -28,16 +660,83 @@ var VaultEntrypoint = class extends WorkerEntrypoint {
 			this.ctx.waitUntil(pool.end());
 		}
 	}
+	/**
+	* 0.15's use: one connection of the hot path's config, for its one statement. Closed once the call is done, and by
+	* its deadline at the latest, so that a call answered `late` lets go of Hyperdrive by then, as its place in admission
+	* lapses soon after (use.ts, `HELD_PAST_DEADLINE_MS`; T170).
+	*/
+	async use(input) {
+		const { prepared, hotDatabase } = this.#behind(await this.#prepared());
+		const pool = new HyperdrivePool(hotDatabase.hyperdrive.connectionString);
+		try {
+			const hot = createDatabase(pool);
+			return await openVault(hot, prepared, hot).use(input);
+		} finally {
+			this.ctx.waitUntil(pool.end(closeBy(input)));
+		}
+	}
+	/** A request's several keys (T167): the same one connection, for its one statement, or two. */
+	async useMany(input) {
+		const { prepared, hotDatabase } = this.#behind(await this.#prepared());
+		if (hotDatabase === void 0) throw new Error("0.15's uses need the hot path's Hyperdrive config: set hotDatabase in vault(…)");
+		const pool = new HyperdrivePool(hotDatabase.hyperdrive.connectionString);
+		try {
+			const hot = createDatabase(pool);
+			return await openVault(hot, prepared, hot).useMany(input);
+		} finally {
+			this.ctx.waitUntil(pool.end(closeBy(input)));
+		}
+	}
+	/** 0.15's use as the request names it: the same one connection, for its read of ids on a miss and its one use. */
+	async useNamed(input) {
+		const { prepared, hotDatabase } = this.#behind(await this.#prepared());
+		const pool = new HyperdrivePool(hotDatabase.hyperdrive.connectionString);
+		try {
+			const hot = createDatabase(pool);
+			return await openVault(hot, prepared, hot).useNamed(input);
+		} finally {
+			this.ctx.waitUntil(pool.end(closeBy(input)));
+		}
+	}
+	/** The vault ready, its checkpointer started from this call first, for at most 2 s (`start`). */
 	async #ready() {
+		const entry = await this.#prepared();
+		if (!entry.started && Date.now() - entry.failed >= START_AGAIN_MS) await start(entry);
+		return entry;
+	}
+	/**
+	* A use waits on no start (T169, R58): it needs no checkpointer, the days of uses the migrations made and the object
+	* makes ahead of time aside. Its isolate's start goes on behind it, once each START_AGAIN_MS until one answers.
+	*/
+	#behind(entry) {
+		if (!entry.started && Date.now() - entry.kicked >= START_AGAIN_MS) {
+			entry.kicked = Date.now();
+			this.ctx.waitUntil(start(entry));
+		}
+		return entry;
+	}
+	async #prepared() {
 		const env = this.env;
 		let entry = ready.get(env);
 		if (entry === void 0) {
 			if (configure === null) throw new Error("the vault Worker must export default vault(…)");
 			const config = configure(env);
-			const prepared = await prepareVault(resolveVaultConfig(config));
+			const { checkpointer: namespace, hotDatabase } = checked(config);
+			const prepared = await prepareVault(resolveVaultConfig(config), {
+				...config.uses === void 0 ? {} : { uses: config.uses },
+				log: "0.15",
+				sealThrough: durableSealThrough(namespace),
+				heldOutside: durableHeldOutside(namespace),
+				callsEndWithRequest: true
+			});
 			entry = ready.get(env) ?? {
 				database: config.database,
-				prepared
+				hotDatabase,
+				checkpointer: namespace,
+				prepared,
+				started: false,
+				failed: -Infinity,
+				kicked: -Infinity
 			};
 			ready.set(env, entry);
 		}
@@ -85,8 +784,14 @@ var VaultEntrypoint = class extends WorkerEntrypoint {
 	async checkpoint() {
 		return this.#call((vault) => vault.checkpoint());
 	}
+	/** What the vault says of itself; its uses over the hot path's own config (`use`), which `#call`'s vault has not. */
 	async about() {
-		return this.#call((vault) => vault.about());
+		const about = await this.#call((vault) => vault.about());
+		return about.log === "0.15" ? {
+			...about,
+			uses: true,
+			batchUses: true
+		} : about;
 	}
 	async keyChecks() {
 		return this.#call((vault) => vault.keyChecks());
@@ -94,15 +799,106 @@ var VaultEntrypoint = class extends WorkerEntrypoint {
 	async verifyLog(input) {
 		return this.#call((vault) => vault.verifyLog(input));
 	}
+	async prepare(input) {
+		return this.#call((vault) => vault.prepare(input));
+	}
+	async waitSealed(input) {
+		return this.#call((vault) => vault.waitSealed(input));
+	}
+	async signIn(input) {
+		return this.#call((vault) => vault.signIn(input));
+	}
+	async revokeCredential(input) {
+		return this.#call((vault) => vault.revokeCredential(input));
+	}
+	async issueToken(input) {
+		return this.#call((vault) => vault.issueToken(input));
+	}
+	async changeBindings(input) {
+		return this.#call((vault) => vault.changeBindings(input));
+	}
+	async cutover(input) {
+		return this.#call((vault) => vault.cutover(input));
+	}
+	async verifyTrees() {
+		return this.#call((vault) => vault.verifyTrees());
+	}
+	async verifyReads(input) {
+		return this.#call((vault) => vault.verifyReads(input));
+	}
+	async vouch(input) {
+		return this.#call((vault) => vault.vouch(input));
+	}
+	/** Whether the checkpointer seals (T169), asked of its object for at most 2 s; no database, and no start awaited. */
+	async sealing() {
+		const { checkpointer: namespace } = this.#behind(await this.#prepared());
+		return durableSealing(namespace)();
+	}
 	/** No HTTP surface: only the app's service binding reaches the vault. */
 	fetch() {
 		return new Response("not found", { status: 404 });
 	}
 };
+/** When a use's connection closes at the latest: its deadline, if it names one (`checkInput` refuses it otherwise). */
+function closeBy(input) {
+	return typeof input?.deadline === "number" && Number.isSafeInteger(input.deadline) ? input.deadline : void 0;
+}
+/**
+* What 0.15's log needs, configured: a setting left out of `vault(…)` is refused here, by name. A Hyperdrive binding
+* left out of wrangler.jsonc is refused before, by `postgres()`; a Durable Object's, here.
+*/
+function checked(config) {
+	if (config.hotDatabase?.hyperdrive?.connectionString === void 0) throw new Error("the vault's uses run through a Hyperdrive config of their own: set hotDatabase in vault(…), postgres(env.HOT_HYPERDRIVE), its login coffre_vault_hot");
+	if (typeof config.checkpointer?.idFromName !== "function") throw new Error("the vault answers a change once its checkpointer has sealed it: set checkpointer in vault(…), env.CHECKPOINTER, and bind the CoffreCheckpointer Durable Object beside the vault");
+	return {
+		hotDatabase: config.hotDatabase,
+		checkpointer: config.checkpointer
+	};
+}
+/**
+* The checkpointer's object started, from a call of this isolate, before it
+* goes on: its alarm set, and it open, so that no call meets a log with no
+* checkpoint yet. Started again is harmless: until one start has answered,
+* each call makes its own and waits for it, never for another call's,
+* which a call may not await on Workers (AGENTS.md).
+* An object that refuses to open (a log it cannot take: docs/restore.md) is
+* started all the same, its alarm set, and says why in its alarms; one out
+* of reach, or that does not answer within 2 s (T169), is tried again by a
+* call 10 s later. Neither stops this call: a use needs no checkpointer (and
+* waits on no start: `#behind`), and a change fails on its seal.
+*/
+async function start(entry) {
+	const projecting = startProjector(entry.checkpointer).catch((error) => console.warn(`coffre vault: the reads' projector did not start: ${error.message}`));
+	try {
+		await startCheckpointer(entry.checkpointer);
+		entry.started = true;
+	} catch (error) {
+		if (error.status === 503) entry.started = true;
+		else entry.failed = Date.now();
+		console.warn(`coffre vault: ${error.message}`);
+	}
+	await projecting;
+}
 /** The vault Worker's default export, `VaultEntrypoint`, configured from its `env`. */
 function vault(configure_) {
 	configure = configure_;
 	return VaultEntrypoint;
 }
+/**
+* 0.15's checkpointer, the Durable Object class a deployment binds beside
+* the vault, configured by the same `vault(env => …)`: its Hyperdrive, its
+* signing key, its witnesses. `export const CoffreCheckpointer = checkpointer()`.
+*/
+function checkpointer() {
+	return checkpointerObject((env) => {
+		if (configure === null) throw new Error("the vault Worker must export default vault(…)");
+		const config = configure(env);
+		return {
+			hyperdrive: config.database.hyperdrive,
+			seed: resolveVaultConfig(config).signingKeys[0],
+			witnesses: config.witnesses
+		};
+	});
+}
 //#endregion
-export { KekBadClaimError, KekUnavailableError, VaultEntrypoint, awsKms, checkpointMessage, derivedSigningKey, postgres, vault, verifyCheckpoint };
+export { KekBadClaimError, KekUnavailableError, VaultEntrypoint, awsKms, checkpointMessage, checkpointer, checkpointerAlarms, checkpointerStatus, derivedSigningKey, durableHeldOutside, durableSealThrough, durableSealing, durableWitness, postgres, r2Archive, startCheckpointer, startProjector, vault, verifyCheckpoint, witnessObject as witness };