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

package/dist/internal/Execution.js

@@ -5,12 +5,15 @@ 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 { 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;
@@ -98,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.");
@@ -191,6 +211,7 @@ const kindCheck = {
 */
 var World = class {
 	runtime;
+	redaction;
 	components = /* @__PURE__ */ new Map();
 	state = empty;
 	opened;
@@ -206,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));
@@ -273,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)
+				});
 			});
 		});
 	}
@@ -340,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.
@@ -370,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.`
 		});
 	}
 	/**
@@ -422,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));
+			});
 		});
 	}
 	/**
@@ -432,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
@@ -533,6 +783,7 @@ 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");
@@ -570,16 +821,19 @@ 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);
 	}
@@ -602,25 +856,28 @@ var World = class {
 		};
 	}
 	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 ? 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.`);
-			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) {
@@ -630,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
@@ -661,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;
+			});
 		});
 	}
 	/**
@@ -753,28 +1017,174 @@ 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;
 	}
@@ -990,6 +1400,7 @@ var World = class {
 	}
 	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.meter.deriveInterval(indexKey(execution.componentPath, table, "by_id"), point([_id]));
@@ -1030,6 +1441,7 @@ var World = class {
 			...fields,
 			...this.fields(document, value)
 		};
+		this.keepRow(execution.componentPath, tableNameFromId(_id), merged);
 		const next = {
 			_id,
 			_creationTime,
@@ -1042,6 +1454,7 @@ var World = class {
 	replace(execution, tableName, id, value) {
 		const document = this.existing(execution, tableName, id, "replace", value);
 		const fields = this.fields(document, value);
+		this.keepRow(execution.componentPath, tableNameFromId(document._id), fields);
 		const next = {
 			...fields,
 			_id: document._id,