@gaganref/confect-test 10.3.1-fork.91 → 10.3.1-fork.93

package/dist/internal/Execution.js

@@ -1,15 +1,19 @@
 import { own } from "./Globals.js";
 import { install } from "./Clock.js";
-import { createFunctionHandle, createTestJwt, deserializeConvexErrorData, evaluateValue, hasPendingValues, parseArgs, parseFunctionHandle, resolveCommittedValues, simpleHash, tableNameFromId, validateFunctionArgs, validateReturnValue } from "./KernelValues.js";
+import { createFunctionHandle, createTestJwt, deserializeConvexErrorData, evaluateValue, hasPendingValues, isSimpleObject, parseArgs, parseFunctionHandle, resolveCommittedValues, simpleHash, tableNameFromId, validateFunctionArgs, validateReturnValue } from "./KernelValues.js";
 import { apply, conflict, empty, wallClock } from "./Kernel.js";
+import { defaults, everything, examined, fromBudget, point } from "./Metering.js";
 import { KernelAttempt } from "./Attempt.js";
 import { bind, current as current$1, fresh, unbound } from "./Invocation.js";
-import { ClosedAttempt, CommitTsNotIncreasing, DrainBudgetExceeded, OptimisticConcurrencyControlFailure, RegisteredAfterOpen, StaleAttempt, UnknownStandingSource, requiresBinary, rowPending } from "./KernelRefusal.js";
+import { ClosedAttempt, CommitTsNotIncreasing, DrainBudgetExceeded, OptimisticConcurrencyControlFailure, RegisteredAfterOpen, SnapshotComponentMismatch, SnapshotJobInconsistent, SnapshotSubscribed, SnapshotWorldBusy, SnapshotWorldRunning, SnapshotWorldUnresolved, StaleAttempt, UnknownStandingSource, requiresBinary, rowPending } from "./KernelRefusal.js";
 import { exportSchema, paginate, stream, validateDocument } from "./KernelQuery.js";
+import { Secrets, failure, keep, mark, markValue, marker, none, sensitiveAt, unmark } from "./Redaction.js";
 import { functions, pending, row, stateOf, table } from "./Scheduling.js";
+import { check, contract, decode, encode } from "./Snapshot.js";
 import { actionGeneric, getFunctionAddress, mutationGeneric, queryGeneric } from "convex/server";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { convexToJson, jsonToConvex } from "convex/values";
+import { CommitTsPlaceholder, compareValues, convexToJson, jsonToConvex } from "convex/values";
+import * as Result from "effect/Result";
 //#region src/internal/Execution.ts
 const ROOT = "";
 const TYPICAL_CONVEX_ID_LENGTH = 32;
@@ -97,6 +101,23 @@ const pinnedTime = () => {
 * `finishAllScheduledFunctions` defaults to.
 */
 const defaultBudget = 100;
+const unresolvedWorld = (name, reason) => new SnapshotWorldUnresolved({
+	name,
+	reason,
+	message: reason === "missing" ? `A snapshot job runs under the test world "${name}", which no world passed to restore is named. Pass that world.` : `Two different test worlds are named "${name}", so a snapshot cannot tell their jobs apart. Name each world uniquely.`
+});
+/**
+* `shape` placed at `at`, or no placement when there is no shape.
+*/
+const placed = (shape, at = []) => shape === void 0 ? [] : [{
+	at,
+	shape
+}];
+const running = (registry, count, what) => new SnapshotWorldRunning({
+	registry,
+	count,
+	message: `The test backend is running ${count} ${what}, whose effects a snapshot would split. Await them first.`
+});
 const current = () => {
 	const execution = executions.getStore();
 	if (execution === void 0) throw new Error("A Convex syscall ran outside any function the test kernel started.");
@@ -190,6 +211,7 @@ const kindCheck = {
 */
 var World = class {
 	runtime;
+	redaction;
 	components = /* @__PURE__ */ new Map();
 	state = empty;
 	opened;
@@ -205,8 +227,31 @@ var World = class {
 	*/
 	floor = Number.NEGATIVE_INFINITY;
 	targets = /* @__PURE__ */ new Map();
-	constructor(schema, modules, runtime = wallClock()) {
+	/**
+	* The raw secrets this world has seen under a secret schema node. Replay
+	* state, kept in memory and never written to an artifact.
+	*/
+	secrets = new Secrets();
+	/**
+	* The live registries `Snapshot.contract.live` names, each a count: calls
+	* from the test, scheduler walks, function executions (nested and detached
+	* ones included) and registered subscribers. Held attempts are `holding`.
+	*/
+	live = {
+		running: 0,
+		walks: 0,
+		functions: 0,
+		subscribers: 0
+	};
+	/**
+	* The latest identity version a subscriber's `authenticate` reached. Each
+	* subscriber starts at the epoch, and each identity change advances it, so a
+	* restored world never hands out a version its source already used.
+	*/
+	identityEpoch = 0;
+	constructor(schema, modules, runtime = wallClock(), redaction = none) {
 		this.runtime = runtime;
+		this.redaction = redaction;
 		installConvexGlobal();
 		install(pinnedTime, () => executions.getStore() !== void 0);
 		this.components.set(ROOT, makeComponent(ROOT, schema, modules));
@@ -272,66 +317,74 @@ var World = class {
 		};
 	}
 	query(caller, reference, args) {
-		return this.open().then(() => {
-			const from = {
-				caller,
-				request: newRequest(caller)
-			};
-			return typeof reference === "function" ? this.runQuery({
-				componentPath: ROOT,
-				udfPath: "inline"
-			}, {
-				handler: reference,
-				args: { type: "any" },
-				returns: null
-			}, args ?? {}, from) : this.queryAt(pathOfReference(reference, ROOT), args, from);
+		return this.during(() => {
+			return this.open().then(() => {
+				const from = {
+					caller,
+					request: newRequest(caller)
+				};
+				return typeof reference === "function" ? this.runQuery({
+					componentPath: ROOT,
+					udfPath: "inline"
+				}, {
+					handler: reference,
+					args: { type: "any" },
+					returns: null
+				}, args ?? {}, from) : this.queryAt(pathOfReference(reference, ROOT), args, from);
+			});
 		});
 	}
 	mutation(caller, reference, args) {
-		return this.open().then(() => {
-			const from = {
-				caller,
-				request: newRequest(caller)
-			};
-			return typeof reference === "function" ? this.runMutation({
-				componentPath: ROOT,
-				udfPath: "inline"
-			}, {
-				handler: reference,
-				args: { type: "any" },
-				returns: null
-			}, args ?? {}, from) : this.mutationAt(pathOfReference(reference, ROOT), args, from);
+		return this.during(() => {
+			return this.open().then(() => {
+				const from = {
+					caller,
+					request: newRequest(caller)
+				};
+				return typeof reference === "function" ? this.runMutation({
+					componentPath: ROOT,
+					udfPath: "inline"
+				}, {
+					handler: reference,
+					args: { type: "any" },
+					returns: null
+				}, args ?? {}, from) : this.mutationAt(pathOfReference(reference, ROOT), args, from);
+			});
 		});
 	}
 	action(caller, reference, args) {
-		return this.open().then(() => {
-			const from = {
-				caller,
-				request: newRequest(caller)
-			};
-			return typeof reference === "function" ? this.runAction({
-				componentPath: ROOT,
-				udfPath: "inline"
-			}, {
-				handler: reference,
-				args: { type: "any" },
-				returns: null
-			}, args ?? {}, from) : this.actionAt(pathOfReference(reference, ROOT), args, from);
+		return this.during(() => {
+			return this.open().then(() => {
+				const from = {
+					caller,
+					request: newRequest(caller)
+				};
+				return typeof reference === "function" ? this.runAction({
+					componentPath: ROOT,
+					udfPath: "inline"
+				}, {
+					handler: reference,
+					args: { type: "any" },
+					returns: null
+				}, args ?? {}, from) : this.actionAt(pathOfReference(reference, ROOT), args, from);
+			});
 		});
 	}
 	run(caller, componentPath, handler) {
-		return this.open().then(() => {
-			this.component(componentPath);
-			return this.runMutation({
-				componentPath,
-				udfPath: "custom"
-			}, {
-				handler,
-				args: { type: "any" },
-				returns: null
-			}, {}, {
-				caller,
-				request: newRequest(caller)
+		return this.during(() => {
+			return this.open().then(() => {
+				this.component(componentPath);
+				return this.runMutation({
+					componentPath,
+					udfPath: "custom"
+				}, {
+					handler,
+					args: { type: "any" },
+					returns: null
+				}, {}, {
+					caller,
+					request: newRequest(caller)
+				});
 			});
 		});
 	}
@@ -339,22 +392,27 @@ var World = class {
 	* Run a mutation to its commit point and hold it as attempt 1.
 	*/
 	prepare(caller, reference, args) {
-		return this.open().then(() => {
-			const functionPath = pathOfReference(reference, ROOT);
-			const resolved = this.resolve(functionPath, "mutation");
-			validateFunctionArgs(resolved.args, args ?? {}, functionPath, false);
-			return this.prepareMutation(functionPath, resolved, args, {
-				caller,
-				request: newRequest(caller)
-			}, 1, current$1()).then((held) => held.view);
+		return this.during(() => {
+			return this.open().then(() => {
+				const functionPath = pathOfReference(reference, ROOT);
+				const resolved = this.resolve(functionPath, "mutation");
+				this.keepArgs(functionPath, args);
+				validateFunctionArgs(resolved.args, args ?? {}, functionPath, false);
+				return this.prepareMutation(functionPath, resolved, args, {
+					caller,
+					request: newRequest(caller)
+				}, 1, current$1()).then((held) => held.view);
+			});
 		});
 	}
 	apply(id) {
-		const held = this.holding.get(id);
-		return held === void 0 ? Promise.reject(new StaleAttempt({
-			id,
-			message: `The test kernel holds no attempt "${id}". It was already applied, or never prepared.`
-		})) : this.applyHeld(held);
+		return this.during(() => {
+			const held = this.holding.get(id);
+			return held === void 0 ? Promise.reject(new StaleAttempt({
+				id,
+				message: `The test kernel holds no attempt "${id}". It was already applied, or never prepared.`
+			})) : this.applyHeld(held);
+		});
 	}
 	/**
 	* The held attempts, oldest first.
@@ -369,37 +427,226 @@ var World = class {
 	* read where an earlier run's ended.
 	*/
 	subscribed(caller, reference, args, pinned) {
-		return this.open().then(() => {
-			const functionPath = pathOfReference(reference, ROOT);
-			const resolved = this.resolve(functionPath, "query");
-			validateFunctionArgs(resolved.args, args ?? {}, functionPath, false);
-			const top = {
-				attempt: new KernelAttempt(this.state),
-				pagination: {
-					calls: 0,
-					journal: pinned.journal,
-					end: null
-				},
-				startTime: pinned.time
-			};
-			const run = (outcome) => ({
-				outcome,
-				snapshot: top.attempt.snapshot.version,
-				reads: top.attempt.reads,
-				observedIdentity: top.attempt.observedIdentity,
-				time: top.attempt.observedTime,
-				journal: pinned.journal ?? top.pagination.end
+		return this.during(() => {
+			return this.open().then(() => {
+				const functionPath = pathOfReference(reference, ROOT);
+				const resolved = this.resolve(functionPath, "query");
+				this.keepArgs(functionPath, args);
+				validateFunctionArgs(resolved.args, args ?? {}, functionPath, false);
+				const top = {
+					attempt: new KernelAttempt(this.state),
+					pagination: {
+						calls: 0,
+						journal: pinned.journal,
+						end: null
+					},
+					startTime: pinned.time
+				};
+				const run = (outcome) => ({
+					outcome,
+					snapshot: top.attempt.snapshot.version,
+					reads: top.attempt.reads,
+					observedIdentity: top.attempt.observedIdentity,
+					time: top.attempt.observedTime,
+					journal: pinned.journal ?? top.pagination.end
+				});
+				return this.runQuery(functionPath, resolved, args, {
+					caller,
+					request: newRequest(caller)
+				}, false, top).then((value) => run({
+					_tag: "returned",
+					value
+				}), (error) => run({
+					_tag: "failed",
+					error
+				}));
 			});
-			return this.runQuery(functionPath, resolved, args, {
-				caller,
-				request: newRequest(caller)
-			}, false, top).then((value) => run({
-				_tag: "returned",
-				value
-			}), (error) => run({
-				_tag: "failed",
-				error
-			}));
+		});
+	}
+	/**
+	* Run `call`, a call from the test, counted as running until it settles.
+	*/
+	during(call) {
+		return this.track("running", call);
+	}
+	/**
+	* Run `work` counted in the live registry `registry` until it settles.
+	*/
+	track(registry, work) {
+		this.live[registry]++;
+		const settle = () => {
+			this.live[registry]--;
+		};
+		try {
+			return work().finally(settle);
+		} catch (error) {
+			settle();
+			throw error;
+		}
+	}
+	/**
+	* How many entries each live registry holds now.
+	*/
+	liveCounts() {
+		return {
+			running: this.live.running,
+			walks: this.live.walks,
+			functions: this.live.functions,
+			held: this.holding.size,
+			subscribers: this.live.subscribers
+		};
+	}
+	/**
+	* Count a subscriber the shim's registry created. Subscribers live as long as
+	* their test, so the count never falls.
+	*/
+	registerSubscriber() {
+		this.live.subscribers++;
+	}
+	/**
+	* The identity version a new subscriber starts at.
+	*/
+	currentIdentityEpoch() {
+		return this.identityEpoch;
+	}
+	/**
+	* The next identity version, for a subscriber whose identity changed.
+	*/
+	nextIdentityEpoch() {
+		return ++this.identityEpoch;
+	}
+	/**
+	* The committed state as snapshot bytes: every component's rows and the
+	* version that wrote each, the write log, the jobs and their targets, the
+	* clock's floor and the identity counters. Each job's world is recorded by
+	* name. Two exports of the same state are the same bytes. A world running a
+	* call or holding attempts refuses, since a snapshot carries neither.
+	*/
+	exportSnapshot() {
+		this.refuseBusy(0, "export");
+		const names = /* @__PURE__ */ new Map();
+		const jobs = /* @__PURE__ */ new Map();
+		for (const byTable of this.state.tables.values()) for (const id of byTable.get("_scheduled_functions")?.keys() ?? []) {
+			const target = this.targets.get(id);
+			if (target === void 0) continue;
+			const world = target.world;
+			if (world !== void 0) {
+				if ((names.get(world.name) ?? world) !== world) throw unresolvedWorld(world.name, "ambiguous");
+				names.set(world.name, world);
+			}
+			jobs.set(id, {
+				functionPath: target.functionPath,
+				standing: target.standing,
+				world: world?.name ?? null
+			});
+		}
+		return encode({
+			components: [...this.components.keys()],
+			state: this.state,
+			floor: this.floor,
+			identity: {
+				nextDocumentId: this.nextDocId,
+				lastCreationTime: this.lastCreationTime,
+				nextAttemptId: this.nextAttemptId,
+				identityEpoch: this.identityEpoch
+			},
+			jobs
+		}, (componentPath, table, json) => mark(json, this.documentPlacements(componentPath, table, json), this.secrets));
+	}
+	/**
+	* Replace this world's state with a snapshot's. The world must register the
+	* snapshot's components, run nothing, and have committed nothing and hold
+	* nothing. Each job's world resolves by name among `worlds`. Bytes whose
+	* digest does not match, and state the kernel could not have reached, refuse
+	* before anything changes.
+	*/
+	restoreSnapshot(bytes, options = {}) {
+		return this.open().then(() => this.restore(bytes, options.worlds ?? [], options.secrets ?? new Secrets()));
+	}
+	restore(bytes, worlds, secrets) {
+		this.refuseBusy(this.state.version, "restore");
+		const decoded = decode(bytes, (json) => unmark(json, secrets));
+		if (Result.isFailure(decoded)) throw decoded.failure;
+		const image = decoded.success;
+		const checked = check(image, table);
+		if (Result.isFailure(checked)) throw checked.failure;
+		const registered = [...this.components.keys()].sort();
+		const snapshot = [...image.components].sort();
+		if (registered.join("\0") !== snapshot.join("\0")) throw new SnapshotComponentMismatch({
+			snapshot,
+			registered,
+			message: `The snapshot holds components ${snapshot.map((p) => `"${p}"`).join(", ")}, but this test backend registers ${registered.map((p) => `"${p}"`).join(", ")}. Register the same components before restoring.`
+		});
+		for (const [id, { functionPath }] of image.jobs) if (!this.exports(functionPath)) throw new SnapshotJobInconsistent({
+			id,
+			reason: "function",
+			message: `The snapshot's job ${id} targets ${functionPath.udfPath} in "${functionPath.componentPath}", which that component does not export.`
+		});
+		const byName = /* @__PURE__ */ new Map();
+		for (const world of worlds) {
+			if ((byName.get(world.name) ?? world) !== world) throw unresolvedWorld(world.name, "ambiguous");
+			byName.set(world.name, world);
+		}
+		const targets = Array.from(image.jobs, ([id, { functionPath, standing, world }]) => {
+			const resolved = world === null ? void 0 : byName.get(world);
+			if (world !== null && resolved === void 0) throw unresolvedWorld(world, "missing");
+			return [id, {
+				functionPath,
+				standing,
+				world: resolved
+			}];
+		});
+		this.state = image.state;
+		this.floor = image.floor;
+		this.nextDocId = image.identity.nextDocumentId;
+		this.lastCreationTime = image.identity.lastCreationTime;
+		this.nextAttemptId = image.identity.nextAttemptId;
+		this.identityEpoch = image.identity.identityEpoch;
+		this.targets.clear();
+		for (const [id, target] of targets) this.targets.set(id, target);
+		this.secrets = secrets.copy();
+	}
+	/**
+	* Whether `functionPath`'s component exports a Convex function there.
+	*/
+	exports({ componentPath, udfPath }) {
+		const [modulePath, exportName = "default"] = udfPath.split(":");
+		const func = this.components.get(componentPath)?.loaded.get(modulePath)?.[exportName];
+		return func?.isQuery === true || func?.isMutation === true || func?.isAction === true;
+	}
+	/**
+	* Refuse a snapshot while any live registry `operation` waits on is
+	* non-empty, or, restoring, once `version` shows the world committed
+	* something of its own.
+	*/
+	refuseBusy(version, operation) {
+		const counts = this.liveCounts();
+		const refusals = {
+			running: (count) => running("running", count, "calls from the test"),
+			walks: (count) => running("walks", count, "scheduler walks"),
+			functions: (count) => running("functions", count, "functions, nested and detached ones included"),
+			held: () => {
+				const held = [...this.holding.keys()];
+				return new SnapshotWorldBusy({
+					version,
+					held,
+					message: `The test backend holds attempts ${held.join(", ")}, which a snapshot does not carry. Apply them first.`
+				});
+			},
+			subscribers: (count) => new SnapshotSubscribed({
+				subscribers: count,
+				message: `The test backend has ${count} subscribers, whose identity versions a restore would rewind. Restore into a test backend no client has subscribed to.`
+			})
+		};
+		for (const key of Object.keys(refusals)) {
+			const { blocks } = contract.live[key];
+			if (operation === "export" && blocks === "restore") continue;
+			if (counts[key] > 0) throw refusals[key](counts[key]);
+		}
+		if (operation === "restore" && version !== 0) throw new SnapshotWorldBusy({
+			version,
+			held: [],
+			message: `The test backend has committed ${version} versions of its own. Restore a snapshot into a fresh test backend.`
 		});
 	}
 	/**
@@ -421,9 +668,11 @@ var World = class {
 	* crosses no future deadline.
 	*/
 	advance(ms, budget = defaultBudget) {
-		return this.open().then(() => {
-			const until = this.now() + ms;
-			return this.walk((pending) => pending.filter((job) => job.scheduledTime <= until), budget).then(() => this.raiseFloor(until));
+		return this.track("walks", () => {
+			return this.open().then(() => {
+				const until = this.now() + ms;
+				return this.walk((pending) => pending.filter((job) => job.scheduledTime <= until), budget).then(() => this.raiseFloor(until));
+			});
 		});
 	}
 	/**
@@ -431,7 +680,9 @@ var World = class {
 	* standing jobs are pending. Every job run counts against `budget`.
 	*/
 	drain(budget = defaultBudget) {
-		return this.open().then(() => this.walk((pending) => pending.filter((job) => !job.standing), budget));
+		return this.track("walks", () => {
+			return this.open().then(() => this.walk((pending) => pending.filter((job) => !job.standing), budget));
+		});
 	}
 	/**
 	* Run the first of `select(pending)` until it is empty, moving the clock to
@@ -532,8 +783,14 @@ var World = class {
 		const target = functionPathOf(args, execution.componentPath);
 		this.component(target.componentPath);
 		const jobArgs = jsonToConvex(args.args);
+		this.keepArgs(target, jobArgs);
 		if (hasPendingValues(jobArgs)) throw new Error(`Invalid arguments for "${target.udfPath}": a scheduled function cannot take an unresolved placeholder value.`);
+		refuse(attempt.meter.schedule(jobArgs, execution.limits));
+		const jobsIndex = indexKey(execution.componentPath, table, "by_id");
+		const parentJob = execution.request.scheduledFunctionId;
+		if (parentJob !== null) refuse(attempt.meter.readInterval(jobsIndex, point([parentJob]), execution.limits));
 		const id = this.generateId(table);
+		attempt.meter.deriveInterval(jobsIndex, point([id]));
 		attempt.write(execution.componentPath, id, row(id, this.creationTime(execution.startTime), target.udfPath, jobArgs, args.ts * 1e3));
 		this.targets.set(id, {
 			functionPath: target,
@@ -548,10 +805,10 @@ var World = class {
 	/**
 	* Cancel a job that has not finished. A finished job stays as it ended.
 	*/
-	cancelJob(attempt, componentPath, id) {
+	cancelJob(attempt, execution, id) {
+		const { componentPath } = execution;
 		validateId(table, id);
-		attempt.readDocument(componentPath, id);
-		const doc = attempt.get(componentPath, id);
+		const doc = this.readById(attempt, execution, id);
 		if (doc === null) throw new Error(`Patch on non-existent document with ID "${id}"`);
 		const { kind } = stateOf(doc);
 		if (kind === "pending" || kind === "inProgress") attempt.write(componentPath, id, {
@@ -564,21 +821,26 @@ var World = class {
 	}
 	queryAt(functionPath, args, from, snapshotOnly = false) {
 		const resolved = this.resolve(functionPath, "query");
+		this.keepArgs(functionPath, args);
 		validateFunctionArgs(resolved.args, args ?? {}, functionPath, from.parent?.attempt !== void 0);
 		return this.runQuery(functionPath, resolved, args, from, snapshotOnly);
 	}
 	mutationAt(functionPath, args, from) {
 		const resolved = this.resolve(functionPath, "mutation");
+		this.keepArgs(functionPath, args);
 		validateFunctionArgs(resolved.args, args ?? {}, functionPath, from.parent?.attempt !== void 0);
 		return this.runMutation(functionPath, resolved, args, from);
 	}
 	actionAt(functionPath, args, from) {
 		const resolved = this.resolve(functionPath, "action");
+		this.keepArgs(functionPath, args);
 		validateFunctionArgs(resolved.args, args ?? {}, functionPath, false);
 		return this.runAction(functionPath, resolved, args, from);
 	}
 	execution(functionPath, udfType, attempt, from, pagination, startTime) {
 		const identity = functionPath.componentPath !== ROOT ? null : from.parent !== void 0 ? from.parent.identity : from.caller.identity;
+		const inherited = attempt === void 0 || from.parent?.attempt === void 0 ? defaults : from.parent.limits;
+		const limits = attempt === void 0 || from.budget === void 0 ? inherited : fromBudget(from.budget, attempt.meter.used(), inherited);
 		return {
 			world: this,
 			componentPath: functionPath.componentPath,
@@ -589,29 +851,33 @@ var World = class {
 			request: from.request,
 			startTime: startTime ?? (from.parent !== void 0 && from.parent.udfType !== "action" ? from.parent.startTime : this.now()),
 			pagination,
-			turn: new Turn()
+			turn: new Turn(),
+			limits
 		};
 	}
 	runQuery(functionPath, resolved, args, from, snapshotOnly = false, top) {
-		const parentAttempt = from.parent?.attempt;
-		const isNested = parentAttempt !== void 0;
-		const attempt = top?.attempt ?? (parentAttempt === void 0 ? new KernelAttempt(this.state) : snapshotOnly ? new KernelAttempt(parentAttempt.snapshot) : parentAttempt);
-		const execution = this.execution(functionPath, "query", attempt, from, top?.pagination ?? (isNested && from.parent?.pagination || {
-			calls: 0,
-			journal: null,
-			end: null
-		}), top?.startTime);
-		const q = queryGeneric({ handler: (ctx, a) => resolved.handler({
-			...ctx,
-			auth: queryAuth(execution)
-		}, a) });
-		return enter(execution, () => q.invokeQuery(JSON.stringify(convexToJson([parseArgs(args)])))).then((raw) => settled(execution, raw)).then((raw) => {
-			const result = jsonToConvex(JSON.parse(raw));
-			if (!isNested && hasPendingValues(result)) throw new Error(`Function ${functionPath.udfPath} return value invalid: queries cannot return an unresolved placeholder value.`);
-			validateReturnValue(resolved.returns, result, "query", functionPath);
-			return result;
-		}).catch((error) => {
-			throw deserializeConvexErrorData(error);
+		return this.track("functions", () => {
+			const parentAttempt = from.parent?.attempt;
+			const isNested = parentAttempt !== void 0;
+			const attempt = top?.attempt ?? (parentAttempt === void 0 ? new KernelAttempt(this.state) : snapshotOnly ? parentAttempt.staleSnapshot() : parentAttempt);
+			const execution = this.execution(functionPath, "query", attempt, from, top?.pagination ?? (isNested && from.parent?.pagination || {
+				calls: 0,
+				journal: null,
+				end: null
+			}), top?.startTime);
+			const q = queryGeneric({ handler: (ctx, a) => resolved.handler({
+				...ctx,
+				auth: queryAuth(execution)
+			}, a) });
+			return enter(execution, () => q.invokeQuery(JSON.stringify(convexToJson([parseArgs(args)])))).then((raw) => settled(execution, raw)).then((raw) => {
+				const result = jsonToConvex(JSON.parse(raw));
+				if (!isNested && hasPendingValues(result)) throw new Error(`Function ${functionPath.udfPath} return value invalid: queries cannot return an unresolved placeholder value.`);
+				this.keepReturns(functionPath, result);
+				validateReturnValue(resolved.returns, result, "query", functionPath);
+				return result;
+			}).catch((error) => {
+				throw deserializeConvexErrorData(error);
+			});
 		});
 	}
 	invokeMutation(execution, resolved, args) {
@@ -621,28 +887,32 @@ var World = class {
 		}, a) });
 		return enter(execution, () => m.invokeMutation(JSON.stringify(convexToJson([parseArgs(args)])))).then((raw) => settled(execution, raw)).then((raw) => {
 			const result = jsonToConvex(JSON.parse(raw));
-			validateReturnValue(resolved.returns, result, "mutation", {
+			const functionPath = {
 				componentPath: execution.componentPath,
 				udfPath: execution.udfPath
-			});
+			};
+			this.keepReturns(functionPath, result);
+			validateReturnValue(resolved.returns, result, "mutation", functionPath);
 			return result;
 		});
 	}
 	runMutation(functionPath, resolved, args, from) {
-		const parentAttempt = from.parent?.attempt;
-		if (parentAttempt !== void 0) {
-			const frame = parentAttempt.child();
-			const execution = this.execution(functionPath, "mutation", frame, from, void 0);
-			return this.invokeMutation(execution, resolved, args).then((result) => frame.drained().then(() => {
-				frame.close();
-				frame.merge();
-				return result;
-			}), (error) => {
-				frame.close();
-				throw deserializeConvexErrorData(error);
-			});
-		}
-		return this.prepareMutation(functionPath, resolved, args, from, 1, current$1()).then((held) => this.publish(held));
+		return this.track("functions", () => {
+			const parentAttempt = from.parent?.attempt;
+			if (parentAttempt !== void 0) {
+				const frame = parentAttempt.child();
+				const execution = this.execution(functionPath, "mutation", frame, from, void 0);
+				return this.invokeMutation(execution, resolved, args).then((result) => frame.drained().then(() => {
+					frame.close();
+					frame.merge();
+					return result;
+				}), (error) => {
+					frame.close();
+					throw deserializeConvexErrorData(error);
+				});
+			}
+			return this.prepareMutation(functionPath, resolved, args, from, 1, current$1()).then((held) => this.publish(held));
+		});
 	}
 	/**
 	* Run one attempt of a top-level mutation against the latest commit, then
@@ -652,34 +922,37 @@ var World = class {
 	* number.
 	*/
 	prepareMutation(functionPath, resolved, args, from, number, bound) {
-		const attempt = new KernelAttempt(this.state, number);
-		const execution = this.execution(functionPath, "mutation", attempt, from, void 0);
-		const run = () => this.invokeMutation(execution, resolved, args);
-		return (bound === void 0 ? run() : bind({
-			...bound,
-			attempt: number
-		}, run)).then((value) => attempt.drained().then(() => ({
-			_tag: "returned",
-			value
-		})), (error) => ({
-			_tag: "failed",
-			error: deserializeConvexErrorData(error)
-		})).then((outcome) => {
-			attempt.close();
-			const held = {
-				view: {
-					id: `attempt-${this.nextAttemptId++}`,
-					request: from.request.requestId,
-					number,
-					snapshot: attempt.snapshot.version,
-					reads: attempt.reads,
-					outcome
-				},
-				attempt,
-				again: (next) => this.prepareMutation(functionPath, resolved, args, from, next, bound)
-			};
-			this.holding.set(held.view.id, held);
-			return held;
+		return this.track("functions", () => {
+			const attempt = new KernelAttempt(this.state, number);
+			const execution = this.execution(functionPath, "mutation", attempt, from, void 0);
+			const run = () => this.invokeMutation(execution, resolved, args);
+			return (bound === void 0 ? run() : bind({
+				...bound,
+				attempt: number
+			}, run)).then((value) => attempt.drained().then(() => ({
+				_tag: "returned",
+				value
+			})), (error) => ({
+				_tag: "failed",
+				error: deserializeConvexErrorData(error)
+			})).then((outcome) => {
+				attempt.close();
+				const held = {
+					view: {
+						id: `attempt-${this.nextAttemptId++}`,
+						functionPath,
+						request: from.request.requestId,
+						number,
+						snapshot: attempt.snapshot.version,
+						reads: attempt.reads,
+						outcome
+					},
+					attempt,
+					again: (next) => this.prepareMutation(functionPath, resolved, args, from, next, bound)
+				};
+				this.holding.set(held.view.id, held);
+				return held;
+			});
 		});
 	}
 	/**
@@ -744,43 +1017,223 @@ var World = class {
 		});
 	}
 	runAction(functionPath, resolved, args, from) {
-		const execution = this.execution(functionPath, "action", void 0, from, void 0);
-		const inner = {
-			request: from.request,
-			parent: execution
+		return this.track("functions", () => {
+			const execution = this.execution(functionPath, "action", void 0, from, void 0);
+			const inner = {
+				request: from.request,
+				parent: execution
+			};
+			const a = actionGeneric({ handler: (ctx, innerArgs) => resolved.handler({
+				...ctx,
+				runQuery: (reference, queryArgs) => this.queryAt(pathOfReference(reference, functionPath.componentPath), queryArgs, inner),
+				runMutation: (reference, mutationArgs) => this.mutationAt(pathOfReference(reference, functionPath.componentPath), mutationArgs, inner),
+				runAction: (reference, actionArgs) => this.actionAt(pathOfReference(reference, functionPath.componentPath), actionArgs, inner),
+				auth: queryAuth(execution)
+			}, innerArgs) });
+			const run = () => enter(execution, () => a.invokeAction(from.request.requestId, JSON.stringify(convexToJson([parseArgs(args)]))));
+			const bound = from.parent === void 0 ? void 0 : current$1();
+			return (bound === void 0 ? run() : bind(fresh(bound.world, functionPath.componentPath, from.request), run)).then((raw) => {
+				const result = jsonToConvex(JSON.parse(raw));
+				this.keepReturns(functionPath, result);
+				validateReturnValue(resolved.returns, result, "action", functionPath);
+				return result;
+			}).catch((error) => {
+				throw deserializeConvexErrorData(error);
+			});
+		});
+	}
+	keepArgs(functionPath, args) {
+		keep(args ?? {}, placed(this.redaction.args(functionPath)), this.secrets);
+	}
+	keepReturns(functionPath, result) {
+		keep(result, placed(this.redaction.returns(functionPath)), this.secrets);
+	}
+	keepRow(componentPath, table, value) {
+		keep(value, placed(this.redaction.table(componentPath, table)), this.secrets);
+	}
+	/**
+	* Where a stored document holds secrets: its table's shape at its root, and
+	* for a job's row, its target's argument shape at `args.0`.
+	*/
+	documentPlacements(componentPath, table$1, doc) {
+		const own = placed(this.redaction.table(componentPath, table$1));
+		if (table$1 !== "_scheduled_functions") return own;
+		const target = this.targets.get(doc._id)?.functionPath ?? {
+			componentPath,
+			udfPath: String(doc.name)
 		};
-		const a = actionGeneric({ handler: (ctx, innerArgs) => resolved.handler({
-			...ctx,
-			runQuery: (reference, queryArgs) => this.queryAt(pathOfReference(reference, functionPath.componentPath), queryArgs, inner),
-			runMutation: (reference, mutationArgs) => this.mutationAt(pathOfReference(reference, functionPath.componentPath), mutationArgs, inner),
-			runAction: (reference, actionArgs) => this.actionAt(pathOfReference(reference, functionPath.componentPath), actionArgs, inner),
-			auth: queryAuth(execution)
-		}, innerArgs) });
-		const run = () => enter(execution, () => a.invokeAction(from.request.requestId, JSON.stringify(convexToJson([parseArgs(args)]))));
-		const bound = from.parent === void 0 ? void 0 : current$1();
-		return (bound === void 0 ? run() : bind(fresh(bound.world, functionPath.componentPath, from.request), run)).then((raw) => {
-			const result = jsonToConvex(JSON.parse(raw));
-			validateReturnValue(resolved.returns, result, "action", functionPath);
-			return result;
-		}).catch((error) => {
-			throw deserializeConvexErrorData(error);
+		return own.concat(placed(this.redaction.args(target), ["args", "0"]));
+	}
+	/**
+	* A copy of the raw secrets this world has kept, for a restore of its
+	* snapshots. It lives in memory only.
+	*/
+	keptSecrets() {
+		return this.secrets.copy();
+	}
+	/**
+	* The failure report for `thrown`, whatever was thrown, with every kept
+	* secret marked. `thrown` itself is never changed.
+	*/
+	redactFailure(thrown) {
+		return failure(thrown, this.secrets);
+	}
+	/**
+	* `outcome` as an artifact writes it: a value marked by the shape of what
+	* `functionPath` returns, a failure as its report.
+	*/
+	redactOutcome(outcome, functionPath) {
+		return outcome._tag === "returned" ? {
+			_tag: "returned",
+			value: markValue(outcome.value, placed(functionPath === void 0 ? void 0 : this.redaction.returns(functionPath)), this.secrets)
+		} : {
+			_tag: "failed",
+			error: this.redactFailure(outcome.error)
+		};
+	}
+	/**
+	* A changed document as an artifact writes it, marked by its table's shape.
+	*/
+	redactChange(change) {
+		const document = (doc) => doc === null ? null : markValue(doc, this.documentPlacements(change.componentPath, tableNameFromId(doc._id) ?? "", doc), this.secrets);
+		return {
+			...change,
+			before: document(change.before),
+			after: document(change.after)
+		};
+	}
+	/**
+	* The function a subscription's or call's reference names, if it names one.
+	*/
+	functionPathOf(reference) {
+		try {
+			return typeof reference === "function" ? void 0 : pathOfReference(reference, ROOT);
+		} catch {
+			return;
+		}
+	}
+	/**
+	* Read records as an artifact writes them. A key or range bound on a field
+	* its table's shape holds secret is the marker, and so is any string holding
+	* a kept secret.
+	*/
+	projectReads(reads) {
+		return reads.map((read) => {
+			if (read.kind === "document") return read;
+			const shape = this.redaction.table(read.componentPath, read.table);
+			const sensitive = (fieldPath) => shape !== void 0 && sensitiveAt(shape, fieldPath.split("."));
+			const value = (fieldPath, v) => sensitive(fieldPath) ? marker : markValue(v, [], this.secrets);
+			const key = (k) => k === null ? null : k.map((v, i) => v === void 0 ? void 0 : value(read.fields[i] ?? "", v));
+			return {
+				...read,
+				range: read.range.map((bound) => ({
+					...bound,
+					value: sensitive(bound.fieldPath) ? marker : convexToJson(markValue(jsonToConvex(bound.value), [], this.secrets))
+				})),
+				after: key(read.after),
+				through: read.through === "end" || read.through === null ? read.through : key(read.through)
+			};
 		});
 	}
+	/**
+	* A held attempt as an artifact writes it: its read records projected and its
+	* outcome marked.
+	*/
+	projectHeld(view) {
+		return {
+			...view,
+			reads: this.projectReads(view.reads),
+			outcome: this.redactOutcome(view.outcome, view.functionPath)
+		};
+	}
+	/**
+	* What `apply` answered as an artifact writes it: an applied result marked by
+	* the shape of what `functionPath` returns, a conflict's next attempt
+	* projected, a refusal as its report.
+	*/
+	projectApplied(applied, functionPath) {
+		switch (applied.kind) {
+			case "applied": {
+				const outcome = this.redactOutcome({
+					_tag: "returned",
+					value: applied.result
+				}, functionPath);
+				return outcome._tag === "returned" ? {
+					...applied,
+					result: outcome.value
+				} : applied;
+			}
+			case "conflict": return {
+				...applied,
+				next: this.projectHeld(applied.next)
+			};
+			case "refused": return {
+				...applied,
+				error: this.redactFailure(applied.error)
+			};
+			case "exhausted": return {
+				...applied,
+				error: this.redactFailure(applied.error)
+			};
+		}
+	}
+	/**
+	* A function's arguments as an artifact writes them, marked by the shape of
+	* its arguments. A command log of provider calls (#137's `commands()`) writes
+	* each command's input through this.
+	*/
+	projectArguments(functionPath, args) {
+		return markValue(args, placed(this.redaction.args(functionPath)), this.secrets);
+	}
 	schema(componentPath) {
 		return this.component(componentPath).schema;
 	}
 	view(execution) {
 		const attempt = transaction(execution);
+		const { componentPath, limits } = execution;
 		return {
-			schema: this.schema(execution.componentPath),
-			scan: (tableName) => attempt.scan(execution.componentPath, tableName),
-			read: (interval, after) => attempt.readInterval({
-				...interval,
-				componentPath: execution.componentPath,
-				after
-			})
+			schema: this.schema(componentPath),
+			scan: (tableName) => attempt.scan(componentPath, tableName),
+			read: ({ index, ...interval }, after) => {
+				const advance = attempt.readInterval({
+					...interval,
+					componentPath,
+					after
+				});
+				return (through) => {
+					advance(through);
+					const examined$1 = examined(interval.range, interval.order, after, through);
+					if (examined$1 !== null) refuse(attempt.meter.readInterval(indexKey(componentPath, interval.table, index), examined$1, limits));
+				};
+			},
+			examine: (table, doc) => refuse(attempt.meter.readDocument(doc, isSystemTable(table), limits))
 		};
 	}
+	/**
+	* Read one document by ID, as the binary's `get_inner` does for a get and for
+	* the document a patch, replace, delete or cancel changes: it reads the ID's
+	* interval of the table's `by_id` index, then charges the document if there
+	* is one (`crates/database/src/transaction.rs:1188-1250`).
+	*/
+	readById(attempt, execution, id) {
+		const { componentPath, limits } = execution;
+		const table = tableNameFromId(id);
+		attempt.readDocument(componentPath, id);
+		refuse(attempt.meter.readInterval(indexKey(componentPath, table, "by_id"), point([id]), limits));
+		const doc = attempt.get(componentPath, id);
+		if (doc !== null) refuse(attempt.meter.readDocument(doc, isSystemTable(table), limits));
+		return doc;
+	}
+	/**
+	* Stage a write to a user table, counted against the execution's limits
+	* first. A write over a limit is not staged (`Writes::update`,
+	* `crates/database/src/writes.rs:241-310`).
+	*/
+	stage(execution, id, doc) {
+		const attempt = transaction(execution);
+		refuse(attempt.meter.write(doc, execution.limits));
+		attempt.write(execution.componentPath, id, doc);
+	}
 	generateId(table) {
 		return String(this.nextDocId++).padStart(TYPICAL_CONVEX_ID_LENGTH - table.length, "0") + table;
 	}
@@ -869,6 +1322,7 @@ var World = class {
 				return JSON.stringify({});
 			case "1.0/count": {
 				const attempt = transaction(execution);
+				refuse(attempt.meter.readInterval(indexKey(execution.componentPath, args.table, "by_id"), everything, execution.limits));
 				attempt.readInterval({
 					kind: "interval",
 					componentPath: execution.componentPath,
@@ -903,10 +1357,11 @@ var World = class {
 				return (op === "1.0/actions/query" ? this.queryAt(functionPath, args.args, from) : op === "1.0/actions/mutation" ? this.mutationAt(functionPath, args.args, from) : this.actionAt(functionPath, args.args, from)).then((value) => JSON.stringify(convexToJson(value)));
 			}
 			case "1.0/runUdf": {
-				const { udfType, args: udfArgs } = args;
+				const { udfType, args: udfArgs, transactionLimits } = args;
 				const from = {
 					request: execution.request,
-					parent: execution
+					parent: execution,
+					budget: budgetOf(transactionLimits)
 				};
 				const functionPath = functionPathOf(args, execution.componentPath);
 				const value = jsonToConvex(udfArgs);
@@ -921,15 +1376,17 @@ var World = class {
 			case "1.0/schedule": return JSON.stringify(convexToJson(this.scheduleJob(transaction(execution), execution, args)));
 			case "1.0/actions/schedule": return JSON.stringify(convexToJson(this.commitNow((attempt) => this.scheduleJob(attempt, execution, args))));
 			case "1.0/cancel_job":
-				this.cancelJob(transaction(execution), execution.componentPath, args.id);
+				this.cancelJob(transaction(execution), execution, args.id);
 				return JSON.stringify({});
 			case "1.0/actions/cancel_job":
-				this.commitNow((attempt) => this.cancelJob(attempt, execution.componentPath, args.id));
+				this.commitNow((attempt) => this.cancelJob(attempt, execution, args.id));
 				return JSON.stringify({});
 			case "1.0/storageDelete":
 			case "1.0/storageGetUrl":
 			case "1.0/storageGenerateUploadUrl": throw rowPending("storage", 6);
-			case "1.0/getTransactionMetrics": throw rowPending("transaction limits", 6);
+			case "1.0/getTransactionMetrics":
+				if (execution.attempt === void 0) throw new Error(`Unknown async operation ${op}`);
+				return JSON.stringify(execution.attempt.meter.metrics(execution.limits));
 			case "1.0/actions/vectorSearch": throw requiresBinary("vectorSearch");
 			default: throw new Error(`The test kernel does not support async syscall: "${op}"`);
 		}
@@ -939,15 +1396,15 @@ var World = class {
 	}
 	get(execution, tableName, id) {
 		validateId(tableName, id);
-		const attempt = transaction(execution);
-		attempt.readDocument(execution.componentPath, id);
-		return attempt.get(execution.componentPath, id);
+		return this.readById(transaction(execution), execution, id);
 	}
 	insert(execution, table, value) {
 		const attempt = transaction(execution);
+		this.keepRow(execution.componentPath, table, value);
 		validateDocument(this.schema(execution.componentPath), table, value);
 		const _id = this.generateId(table);
-		attempt.write(execution.componentPath, _id, {
+		attempt.meter.deriveInterval(indexKey(execution.componentPath, table, "by_id"), point([_id]));
+		this.stage(execution, _id, {
 			...value,
 			_id,
 			_creationTime: this.creationTime(execution.startTime)
@@ -966,9 +1423,7 @@ var World = class {
 	existing(execution, tableName, id, write, value) {
 		validateId(tableName, id);
 		if (value !== void 0 && typeof value !== "object") throw new Error(`Invalid argument \`value\` in \`db.${write}\`, expected object but got '${typeof value}': ${value}`);
-		const attempt = transaction(execution);
-		attempt.readDocument(execution.componentPath, id);
-		const document = attempt.get(execution.componentPath, id);
+		const document = this.readById(transaction(execution), execution, id);
 		if (document === null) throw new Error(write === "delete" ? "Delete on non-existent doc" : `${write === "patch" ? "Patch" : "Replace"} on non-existent document with ID "${id}"`);
 		return document;
 	}
@@ -986,27 +1441,89 @@ var World = class {
 			...fields,
 			...this.fields(document, value)
 		};
-		validateDocument(this.schema(execution.componentPath), tableNameFromId(_id), merged);
-		transaction(execution).write(execution.componentPath, _id, {
+		this.keepRow(execution.componentPath, tableNameFromId(_id), merged);
+		const next = {
 			_id,
 			_creationTime,
 			...merged
-		});
+		};
+		if (sameDocument(document, next)) return;
+		validateDocument(this.schema(execution.componentPath), tableNameFromId(_id), merged);
+		this.stage(execution, _id, next);
 	}
 	replace(execution, tableName, id, value) {
 		const document = this.existing(execution, tableName, id, "replace", value);
 		const fields = this.fields(document, value);
-		validateDocument(this.schema(execution.componentPath), tableNameFromId(document._id), fields);
-		transaction(execution).write(execution.componentPath, document._id, {
+		this.keepRow(execution.componentPath, tableNameFromId(document._id), fields);
+		const next = {
 			...fields,
 			_id: document._id,
 			_creationTime: document._creationTime
-		});
+		};
+		if (sameDocument(document, next)) return;
+		validateDocument(this.schema(execution.componentPath), tableNameFromId(document._id), fields);
+		this.stage(execution, document._id, next);
 	}
 	remove(execution, tableName, id) {
 		const document = this.existing(execution, tableName, id, "delete", void 0);
-		transaction(execution).write(execution.componentPath, document._id, null);
+		this.stage(execution, document._id, null);
+	}
+};
+const refuse = (error) => {
+	if (error !== void 0) throw error;
+};
+/**
+* One index of one table in one component, as the binary keys a read set.
+*/
+const indexKey = (componentPath, table, index) => `${componentPath}\u0000${table}\u0000${index}`;
+const isSystemTable = (table) => table.startsWith("_");
+const isFieldMap = (value) => typeof value === "object" && value !== null && isSimpleObject(value);
+/**
+* Whether two stored values are the same value, an unresolved commit timestamp
+* included. The binary compares pending values structurally, so a pending
+* timestamp equals only another pending timestamp, at any depth (`PendingValue`
+* derives `PartialEq`, `crates/value/src/pending.rs:56-75`, as
+* `PendingDocument` does, `crates/common/src/document.rs:624-632`). Concrete
+* values compare by `ConvexValue`'s total order
+* (`crates/value/src/sorting.rs:468-472`), which `compareValues` follows.
+* `compareValues` alone ranks a pending timestamp as the largest int64, so it
+* cannot tell the two apart. An object field set to `undefined` is absent.
+*/
+const sameValue = (a, b) => {
+	const aPending = a instanceof CommitTsPlaceholder;
+	const bPending = b instanceof CommitTsPlaceholder;
+	if (aPending || bPending) return aPending && bPending;
+	if (Array.isArray(a) || Array.isArray(b)) return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((value, i) => sameValue(value, b[i]));
+	if (isFieldMap(a) || isFieldMap(b)) {
+		if (!isFieldMap(a) || !isFieldMap(b)) return false;
+		const fields = (value) => Object.entries(value).filter(([, field]) => field !== void 0);
+		const aFields = fields(a);
+		const bFields = new Map(fields(b));
+		return aFields.length === bFields.size && aFields.every(([key, field]) => bFields.has(key) && sameValue(field, bFields.get(key)));
+	}
+	return compareValues(a, b) === 0;
+};
+/**
+* Whether a patch or replace leaves a document as it was. The binary then
+* writes nothing (`patch_inner` and `replace_inner`,
+* `crates/database/src/transaction.rs:713-790`).
+*/
+const sameDocument = (before, after) => sameValue(before, after);
+/**
+* A nested call's `transactionLimits`. The binary reads each field as an
+* unsigned integer and ignores fields it does not know (`TransactionLimits`,
+* `crates/database/src/execution_size.rs:62-95`).
+*/
+const budgetOf = (limits) => {
+	if (limits === void 0 || limits === null) return void 0;
+	const budget = {};
+	for (const metric of Object.keys(defaults)) {
+		const value = limits[metric];
+		if (value === void 0) continue;
+		if (typeof value !== "number" || !Number.isInteger(value) || value < 0) throw new Error(`Invalid arguments for \`runUdf\`: transactionLimits.${metric} must be a non-negative integer, got ${JSON.stringify(value)}`);
+		budget[metric] = value;
 	}
+	return budget;
 };
 const closed = (execution, operation) => new ClosedAttempt({
 	operation,