@gaganref/confect-test 10.3.1-fork.88 → 10.3.1-fork.89

package/dist/internal/KernelValues.js

@@ -0,0 +1,266 @@
+import { CommitTsPlaceholder, compareValues, convexToJson, jsonToConvex } from "convex/values";
+//#region src/internal/KernelValues.ts
+function tableNameFromId(id) {
+	const match = id.match(/^[0-9]+/);
+	if (!match || match[0].length === id.length) return null;
+	return id.slice(match[0].length);
+}
+function deserializeConvexErrorData(thrown) {
+	if (typeof thrown === "object" && thrown !== null && Symbol.for("ConvexError") in thrown && typeof thrown.data === "string") try {
+		thrown.data = jsonToConvex(JSON.parse(thrown.data));
+	} catch {}
+	return thrown;
+}
+function isSimpleObject(value) {
+	const isObject = typeof value === "object";
+	const prototype = Object.getPrototypeOf(value);
+	const isSimple = prototype === null || prototype === Object.prototype || prototype?.constructor?.name === "Object";
+	return isObject && isSimple;
+}
+const MAX_COMMIT_TS = 2n ** 63n - 1n;
+function hasPendingValues(value) {
+	if (value instanceof CommitTsPlaceholder) return true;
+	if (Array.isArray(value)) return value.some(hasPendingValues);
+	if (value !== null && value !== void 0 && isSimpleObject(value)) return Object.values(value).some(hasPendingValues);
+	return false;
+}
+function resolvePendingValues(value) {
+	return substituteCommitTs(value, MAX_COMMIT_TS);
+}
+function resolveCommittedValues(value, commitTs) {
+	return substituteCommitTs(value, commitTs);
+}
+function substituteCommitTs(value, commitTs) {
+	if (!hasPendingValues(value)) return value;
+	if (value instanceof CommitTsPlaceholder) return commitTs;
+	if (Array.isArray(value)) return value.map((v) => substituteCommitTs(v, commitTs));
+	return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, substituteCommitTs(v, commitTs)]));
+}
+function evaluateFieldPath(fieldPath, document) {
+	const pathParts = fieldPath.split(".");
+	let result = document;
+	for (const p of pathParts) result = result !== void 0 && result !== null && isSimpleObject(result) ? result[p] : void 0;
+	return result === void 0 ? void 0 : resolvePendingValues(result);
+}
+function evaluateFilter(document, filter) {
+	if (filter.$eq !== void 0) return compareValues(evaluateFilter(document, filter.$eq[0]), evaluateFilter(document, filter.$eq[1])) === 0;
+	if (filter.$neq !== void 0) return compareValues(evaluateFilter(document, filter.$neq[0]), evaluateFilter(document, filter.$neq[1])) !== 0;
+	if (filter.$and !== void 0) return filter.$and.every((child) => evaluateFilter(document, child));
+	if (filter.$or !== void 0) return filter.$or.some((child) => evaluateFilter(document, child));
+	if (filter.$not !== void 0) return !evaluateFilter(document, filter.$not);
+	if (filter.$gt !== void 0) return evaluateFilter(document, filter.$gt[0]) > evaluateFilter(document, filter.$gt[1]);
+	if (filter.$gte !== void 0) return evaluateFilter(document, filter.$gte[0]) >= evaluateFilter(document, filter.$gte[1]);
+	if (filter.$lt !== void 0) return evaluateFilter(document, filter.$lt[0]) < evaluateFilter(document, filter.$lt[1]);
+	if (filter.$lte !== void 0) return evaluateFilter(document, filter.$lte[0]) <= evaluateFilter(document, filter.$lte[1]);
+	if (filter.$add !== void 0) return evaluateFilter(document, filter.$add[0]) + evaluateFilter(document, filter.$add[1]);
+	if (filter.$sub !== void 0) return evaluateFilter(document, filter.$sub[0]) - evaluateFilter(document, filter.$sub[1]);
+	if (filter.$mul !== void 0) return evaluateFilter(document, filter.$mul[0]) * evaluateFilter(document, filter.$mul[1]);
+	if (filter.$div !== void 0) return evaluateFilter(document, filter.$div[0]) / evaluateFilter(document, filter.$div[1]);
+	if (filter.$mod !== void 0) return evaluateFilter(document, filter.$mod[0]) % evaluateFilter(document, filter.$mod[1]);
+	if (filter.$field !== void 0) return evaluateFieldPath(filter.$field, document);
+	if (filter.$literal !== void 0) return evaluateQueryValue(filter.$literal);
+	throw new Error(`not implemented: ${JSON.stringify(filter)}`);
+}
+function evaluateRangeFilter(document, expr) {
+	const result = evaluateFieldPath(expr.fieldPath, document);
+	const value = evaluateQueryValue(expr.value);
+	switch (expr.type) {
+		case "Eq": return compareValues(result, value) === 0;
+		case "Gt": return compareValues(result, value) > 0;
+		case "Gte": return compareValues(result, value) >= 0;
+		case "Lt": return compareValues(result, value) < 0;
+		case "Lte": return compareValues(result, value) <= 0;
+	}
+}
+function evaluateValue(value) {
+	if (typeof value === "object" && value !== null && "$undefined" in value) return;
+	return jsonToConvex(value);
+}
+function evaluateQueryValue(value) {
+	const evaluatedValue = evaluateValue(value);
+	return evaluatedValue === void 0 ? void 0 : resolvePendingValues(evaluatedValue);
+}
+function validateIndexRangeExpression(source, fields) {
+	let fieldIndex = 0;
+	let state = "eq";
+	for (const [filterIndex, filter] of source.range.entries()) {
+		if (state === "done") throw new Error(`Incorrect operator used in \`withIndex\`, cannot chain more operators after both \`.gt\` and \`.lt\` were already used, got \`${printIndexOperator(filter)}\`.`);
+		const filterType = filter.type == "Gt" || filter.type == "Gte" ? "gt" : filter.type == "Lt" || filter.type == "Lte" ? "lt" : "eq";
+		switch (`${state}|${filterType}`) {
+			case "eq|eq":
+			case "eq|gt":
+			case "eq|lt":
+				if (filter.fieldPath === fields[fieldIndex]) {
+					fieldIndex += 1;
+					state = filterType;
+					continue;
+				}
+				throw new Error(`Incorrect field used in \`withIndex\`, expected "${fields[fieldIndex]}", got "${filter.fieldPath}"`);
+			case "lt|gt":
+			case "gt|lt":
+				if (fieldIndex > 0 && filter.fieldPath === fields[fieldIndex - 1]) {
+					state = "done";
+					continue;
+				}
+				throw new Error(`Incorrect field used in \`withIndex\`, \`.gt\` and \`.lt\` must operate on the same field, expected "${fields[fieldIndex - 1]}", got "${filter.fieldPath}"`);
+			default: throw new Error(`Incorrect operator used in \`withIndex\`, cannot chain \`.${filter.type.toLowerCase()}()\` after \`.${source.range[filterIndex - 1].type.toLowerCase()}()\``);
+		}
+	}
+}
+function printIndexOperator(filter) {
+	return `.${filter.type.toLowerCase()}(${filter.fieldPath}, ${JSON.stringify(filter.value)})`;
+}
+function validateFieldNames(validator) {
+	if (validator.type === "object") Object.keys(validator.value).forEach((fieldName) => {
+		if (!isValidIdentifier(fieldName)) throw new Error(`Field names must be valid identifiers, got "${fieldName}"`);
+	});
+	if (validator.type === "union") validator.value.forEach(validateFieldNames);
+}
+function isValidIdentifier(name) {
+	return /(^_(id|creationTime)$)|^[a-zA-Z][a-zA-Z0-9_]*$/.test(name);
+}
+function validateValidator(validator, value) {
+	switch (validator.type) {
+		case "null":
+			if (value !== null) throw new Error(`Validator error: Expected \`null\`, got \`${value}\``);
+			return;
+		case "number":
+			if (typeof value !== "number") throw new Error(`Validator error: Expected \`number\`, got \`${value}\``);
+			return;
+		case "bigint":
+			if (typeof value !== "bigint") throw new Error(`Validator error: Expected \`bigint\`, got \`${value}\``);
+			return;
+		case "commitTs":
+			if (typeof value !== "bigint" && !(value instanceof CommitTsPlaceholder)) throw new Error(`Validator error: Expected \`v.commitTs()\`, got \`${value}\``);
+			return;
+		case "boolean":
+			if (typeof value !== "boolean") throw new Error(`Validator error: Expected \`boolean\`, got \`${value}\``);
+			return;
+		case "string":
+			if (typeof value !== "string") throw new Error(`Validator error: Expected \`string\`, got \`${value}\``);
+			return;
+		case "bytes":
+			if (!(value instanceof ArrayBuffer)) throw new Error(`Validator error: Expected \`ArrayBuffer\`, got \`${value}\``);
+			return;
+		case "any": return;
+		case "literal":
+			if (value !== validator.value) throw new Error(`Validator error: Expected \`${validator.value}\`, got \`${value}\``);
+			return;
+		case "id":
+			if (typeof value !== "string") throw new Error(`Validator error: Expected \`string\`, got \`${value}\``);
+			if (tableNameFromId(value) !== validator.tableName) throw new Error(`Validator error: Expected ID for table "${validator.tableName}", got \`${value}\``);
+			return;
+		case "array":
+			if (!Array.isArray(value)) throw new Error(`Validator error: Expected \`Array\`, got \`${value}\``);
+			for (const v of value) validateValidator(validator.value, v);
+			return;
+		case "union": {
+			let isValid = false;
+			for (const v of validator.value) try {
+				validateValidator(v, value);
+				isValid = true;
+				break;
+			} catch {}
+			if (!isValid) throw new Error(`Validator error: Expected one of ${validator.value.map((v) => v.type).join(", ")}, got \`${JSON.stringify(convexToJson(value))}\``);
+			return;
+		}
+		case "object":
+			if (typeof value !== "object") throw new Error(`Validator error: Expected \`object\`, got \`${value}\``);
+			if (!isSimpleObject(value)) throw new Error(`Validator error: Expected a plain old JavaScript \`object\`, got \`${value}\``);
+			for (const [k, { fieldType, optional }] of Object.entries(validator.value)) if (value[k] === void 0) {
+				if (!optional) throw new Error(`Validator error: Missing required field \`${k}\` in object`);
+			} else validateValidator(fieldType, value[k]);
+			for (const k of Object.keys(value)) if (validator.value[k] === void 0) throw new Error(`Validator error: Unexpected field \`${k}\` in object`);
+			return;
+		case "record":
+			if (value === null || typeof value !== "object" || !isSimpleObject(value)) throw new Error(`Validator error: Expected a plain old JavaScript \`object\` for a record, got \`${value}\``);
+			for (const [k, fieldValue] of Object.entries(value)) {
+				validateValidator(validator.keys, k);
+				if (fieldValue !== void 0) validateValidator(validator.values.fieldType, fieldValue);
+			}
+			return;
+		default: throw new Error(`The test kernel cannot check a validator of type \`${validator.type}\`.`);
+	}
+}
+const JWT_CLAIM_BY_IDENTITY_ATTRIBUTE = {
+	subject: "sub",
+	issuer: "iss",
+	name: "name",
+	givenName: "given_name",
+	familyName: "family_name",
+	nickname: "nickname",
+	preferredUsername: "preferred_username",
+	profileUrl: "profile",
+	pictureUrl: "picture",
+	email: "email",
+	emailVerified: "email_verified",
+	gender: "gender",
+	birthday: "birthdate",
+	timezone: "zoneinfo",
+	language: "locale",
+	phoneNumber: "phone_number",
+	phoneNumberVerified: "phone_number_verified",
+	address: "address",
+	updatedAt: "updated_at"
+};
+function base64UrlEncode(value) {
+	return base64UrlEncodeBytes(new TextEncoder().encode(value));
+}
+function base64UrlEncodeBytes(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function createTestJwt(identity) {
+	const claims = Object.create(null);
+	for (const [attribute, value] of Object.entries(identity)) {
+		if (value === void 0 || attribute === "tokenIdentifier") continue;
+		const claimName = Object.hasOwn(JWT_CLAIM_BY_IDENTITY_ATTRIBUTE, attribute) ? JWT_CLAIM_BY_IDENTITY_ATTRIBUTE[attribute] : attribute;
+		claims[claimName] = value;
+	}
+	claims.iss = identity.issuer;
+	claims.sub = identity.subject;
+	return `${base64UrlEncode(JSON.stringify({
+		alg: "none",
+		typ: "JWT"
+	}))}.${base64UrlEncode(JSON.stringify(claims))}.`;
+}
+function parseArgs(args) {
+	if (args === void 0) return {};
+	if (!isSimpleObject(args)) throw new Error(`The arguments to a Convex function must be an object. Received: ${args}`);
+	return args;
+}
+function validateFunctionArgs(argsValidator, args, functionPath, allowPendingValues) {
+	if (!allowPendingValues && hasPendingValues(args)) throw new Error(`Invalid arguments for "${functionPath.udfPath}": an unresolved placeholder value can only be passed to a query or mutation called from a mutation`);
+	validateValidator(argsValidator, resolvePendingValues(args));
+}
+function validateReturnValue(returnsValidator, result, functionType, functionPath) {
+	if (returnsValidator !== null) try {
+		validateValidator(returnsValidator, resolvePendingValues(result));
+	} catch (e) {
+		throw new Error(`Return value validation failed for ${functionType} "${functionPath.udfPath}":\n${e.message}`, { cause: e });
+	}
+}
+function createFunctionHandle(functionPath) {
+	return `function://${functionPath.componentPath};${functionPath.udfPath}`;
+}
+function parseFunctionHandle(handle) {
+	const [componentPath, udfPath] = handle.split("function://")[1].split(";");
+	return {
+		componentPath,
+		udfPath
+	};
+}
+function simpleHash(string) {
+	let hash = 0;
+	for (let i = 0; i < string.length; i++) {
+		const char = string.charCodeAt(i);
+		hash = (hash << 5) - hash + char;
+		hash = hash & hash;
+	}
+	return hash;
+}
+//#endregion
+export { JWT_CLAIM_BY_IDENTITY_ATTRIBUTE, MAX_COMMIT_TS, base64UrlEncode, base64UrlEncodeBytes, createFunctionHandle, createTestJwt, deserializeConvexErrorData, evaluateFieldPath, evaluateFilter, evaluateQueryValue, evaluateRangeFilter, evaluateValue, hasPendingValues, isSimpleObject, isValidIdentifier, parseArgs, parseFunctionHandle, printIndexOperator, resolveCommittedValues, resolvePendingValues, simpleHash, substituteCommitTs, tableNameFromId, validateFieldNames, validateFunctionArgs, validateIndexRangeExpression, validateReturnValue, validateValidator };
+
+//# sourceMappingURL=KernelValues.js.map

package/dist/internal/KernelValues.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"KernelValues.js","names":["unknown"],"sources":["../../src/internal/KernelValues.ts"],"sourcesContent":["// Derived from convex-test 0.0.65 (index.ts), Copyright Convex, Inc.,\n// licensed under the Apache License, Version 2.0\n// (https://www.apache.org/licenses/LICENSE-2.0). The value, filter, range,\n// validator and argument rules are kept as convex-test states them, so the\n// kernel answers a function the way convex-test does. The storage, attempts\n// and execution around them are the kernel's own.\n\nimport type { GenericDocument } from \"convex/server\";\nimport {\n  CommitTsPlaceholder,\n  type GenericId,\n  type JSONValue,\n  type Value,\n  compareValues,\n  convexToJson,\n  jsonToConvex,\n} from \"convex/values\";\n\n/**\n * A function address inside one test backend: its component and its\n * `module:export` path.\n */\nexport type FunctionPath = {\n  readonly componentPath: string;\n  readonly udfPath: string;\n};\n\nexport type FilterJson =\n  | { $eq: [FilterJson, FilterJson] }\n  | { $field: string }\n  | JSONValue;\n\nexport type QueryOperator = { filter: FilterJson } | { limit: number };\nexport type Source =\n  | { type: \"FullTableScan\"; tableName: string; order: \"asc\" | \"desc\" | null }\n  | {\n      type: \"IndexRange\";\n      indexName: string;\n      range: ReadonlyArray<SerializedRangeExpression>;\n      order: \"asc\" | \"desc\" | null;\n    }\n  | {\n      type: \"Search\";\n      indexName: string;\n      filters: ReadonlyArray<SerializedSearchFilter>;\n    };\n\nexport type SerializedQuery = {\n  source: Source;\n  operators: Array<QueryOperator>;\n};\n\nexport type SerializedRangeExpression = {\n  type: \"Eq\" | \"Gt\" | \"Gte\" | \"Lt\" | \"Lte\";\n  fieldPath: string;\n  value: JSONValue;\n};\n\nexport type SerializedSearchFilter =\n  | {\n      type: \"Search\";\n      fieldPath: string;\n      value: string;\n    }\n  | {\n      type: \"Eq\";\n      fieldPath: string;\n      value: JSONValue;\n    };\n\nexport type StoredDocument = GenericDocument & {\n  _id: DocumentId;\n  _creationTime: number;\n};\n\nexport type Index = {\n  indexDescriptor: string;\n  fields: string[];\n};\n\nexport type TableName = string;\n\nexport type DocumentId = GenericId<TableName>;\n\nexport function tableNameFromId(id: string) {\n  const match = id.match(/^[0-9]+/);\n  if (!match || match[0].length === id.length) {\n    return null;\n  }\n  return id.slice(match[0].length);\n}\nexport function deserializeConvexErrorData(thrown: unknown) {\n  if (\n    typeof thrown === \"object\" &&\n    thrown !== null &&\n    Symbol.for(\"ConvexError\") in thrown &&\n    typeof (thrown as { data: unknown }).data === \"string\"\n  ) {\n    try {\n      (thrown as { data: unknown }).data = jsonToConvex(\n        JSON.parse((thrown as { data: string }).data),\n      );\n    } catch {\n      // Data wasn't a serialized JSON string — leave it untouched.\n    }\n  }\n  return thrown;\n}\n\nexport function isSimpleObject(value: unknown) {\n  const isObject = typeof value === \"object\";\n  const prototype = Object.getPrototypeOf(value);\n  const isSimple =\n    prototype === null ||\n    prototype === Object.prototype ||\n    // Objects generated from other contexts (e.g. across Node.js `vm` modules) will not satisfy the previous\n    // conditions but are still simple objects.\n    prototype?.constructor?.name === \"Object\";\n  return isObject && isSimple;\n}\n\n// Commit timestamp placeholders are resolved to `i64::MAX` before commit.\nexport const MAX_COMMIT_TS = 2n ** 63n - 1n;\n\nexport function hasPendingValues(value: Value): boolean {\n  if (value instanceof CommitTsPlaceholder) {\n    return true;\n  }\n  if (Array.isArray(value)) {\n    return value.some(hasPendingValues);\n  }\n  if (value !== null && value !== undefined && isSimpleObject(value)) {\n    return Object.values(value).some(hasPendingValues);\n  }\n  return false;\n}\n\n// The value as the transaction sees it before committing.\nexport function resolvePendingValues(value: Value): Value {\n  return substituteCommitTs(value, MAX_COMMIT_TS);\n}\n\n// The value as it is committed.\nexport function resolveCommittedValues<T extends Value>(\n  value: T,\n  commitTs: bigint,\n): T {\n  return substituteCommitTs(value, commitTs);\n}\n\nexport function substituteCommitTs<T extends Value>(\n  value: T,\n  commitTs: bigint,\n): T {\n  if (!hasPendingValues(value)) {\n    return value;\n  }\n  if (value instanceof CommitTsPlaceholder) {\n    return commitTs as T;\n  }\n  if (Array.isArray(value)) {\n    return value.map((v) => substituteCommitTs(v, commitTs)) as T;\n  }\n  return Object.fromEntries(\n    Object.entries(value as object).map(([k, v]) => [\n      k,\n      substituteCommitTs(v, commitTs),\n    ]),\n  ) as T;\n}\n\nexport function evaluateFieldPath(fieldPath: string, document: any) {\n  const pathParts = fieldPath.split(\".\");\n  let result: Value | undefined = document;\n  for (const p of pathParts) {\n    result =\n      result !== undefined && result !== null && isSimpleObject(result)\n        ? (result as any)[p]\n        : undefined;\n  }\n  return result === undefined ? undefined : resolvePendingValues(result);\n}\n\nexport function evaluateFilter(\n  document: GenericDocument,\n  filter: any,\n): Value | undefined {\n  if (filter.$eq !== undefined) {\n    return (\n      compareValues(\n        evaluateFilter(document, filter.$eq[0]),\n        evaluateFilter(document, filter.$eq[1]),\n      ) === 0\n    );\n  }\n  if (filter.$neq !== undefined) {\n    return (\n      compareValues(\n        evaluateFilter(document, filter.$neq[0]),\n        evaluateFilter(document, filter.$neq[1]),\n      ) !== 0\n    );\n  }\n  if (filter.$and !== undefined) {\n    return filter.$and.every((child: any) => evaluateFilter(document, child));\n  }\n  if (filter.$or !== undefined) {\n    return filter.$or.some((child: any) => evaluateFilter(document, child));\n  }\n  if (filter.$not !== undefined) {\n    return !evaluateFilter(document, filter.$not);\n  }\n  if (filter.$gt !== undefined) {\n    return (\n      evaluateFilter(document, filter.$gt[0])! >\n      evaluateFilter(document, filter.$gt[1])!\n    );\n  }\n  if (filter.$gte !== undefined) {\n    return (\n      evaluateFilter(document, filter.$gte[0])! >=\n      evaluateFilter(document, filter.$gte[1])!\n    );\n  }\n  if (filter.$lt !== undefined) {\n    return (\n      evaluateFilter(document, filter.$lt[0])! <\n      evaluateFilter(document, filter.$lt[1])!\n    );\n  }\n  if (filter.$lte !== undefined) {\n    return (\n      evaluateFilter(document, filter.$lte[0])! <=\n      evaluateFilter(document, filter.$lte[1])!\n    );\n  }\n  if (filter.$add !== undefined) {\n    return (\n      (evaluateFilter(document, filter.$add[0]) as number) +\n      (evaluateFilter(document, filter.$add[1]) as number)\n    );\n  }\n  if (filter.$sub !== undefined) {\n    return (\n      (evaluateFilter(document, filter.$sub[0]) as number) -\n      (evaluateFilter(document, filter.$sub[1]) as number)\n    );\n  }\n  if (filter.$mul !== undefined) {\n    return (\n      (evaluateFilter(document, filter.$mul[0]) as number) *\n      (evaluateFilter(document, filter.$mul[1]) as number)\n    );\n  }\n  if (filter.$div !== undefined) {\n    return (\n      (evaluateFilter(document, filter.$div[0]) as number) /\n      (evaluateFilter(document, filter.$div[1]) as number)\n    );\n  }\n  if (filter.$mod !== undefined) {\n    return (\n      (evaluateFilter(document, filter.$mod[0]) as number) %\n      (evaluateFilter(document, filter.$mod[1]) as number)\n    );\n  }\n  if (filter.$field !== undefined) {\n    return evaluateFieldPath(filter.$field, document);\n  }\n  if (filter.$literal !== undefined) {\n    return evaluateQueryValue(filter.$literal);\n  }\n  throw new Error(`not implemented: ${JSON.stringify(filter)}`);\n}\n\nexport function evaluateRangeFilter(\n  document: GenericDocument,\n  expr: SerializedRangeExpression,\n) {\n  const result = evaluateFieldPath(expr.fieldPath, document);\n  const value = evaluateQueryValue(expr.value);\n  switch (expr.type) {\n    case \"Eq\":\n      return compareValues(result, value) === 0;\n    case \"Gt\":\n      return compareValues(result, value) > 0;\n    case \"Gte\":\n      return compareValues(result, value) >= 0;\n    case \"Lt\":\n      return compareValues(result, value) < 0;\n    case \"Lte\":\n      return compareValues(result, value) <= 0;\n  }\n}\n\n// A value used as a written field.\nexport function evaluateValue(value: JSONValue) {\n  if (typeof value === \"object\" && value !== null && \"$undefined\" in value) {\n    return undefined;\n  }\n  return jsonToConvex(value);\n}\n\n// A value used as a query bound or literal.\nexport function evaluateQueryValue(value: JSONValue) {\n  const evaluatedValue = evaluateValue(value);\n  return evaluatedValue === undefined\n    ? undefined\n    : resolvePendingValues(evaluatedValue);\n}\n\n// An index range expression is always a chained list of:\n//\n// 0 or more equality expressions defined with .eq.\n// [Optionally] A lower bound expression defined with .gt or .gte.\n// [Optionally] An upper bound expression defined with .lt or .lte.\nexport function validateIndexRangeExpression(\n  source: Source & { type: \"IndexRange\" },\n  fields: string[],\n) {\n  let fieldIndex = 0;\n  let state: \"eq\" | \"gt\" | \"lt\" | \"done\" = \"eq\";\n  for (const [filterIndex, filter] of source.range.entries()) {\n    if (state === \"done\") {\n      throw new Error(\n        `Incorrect operator used in \\`withIndex\\`, cannot chain ` +\n          `more operators after both \\`.gt\\` and \\`.lt\\` were already used, ` +\n          `got \\`${printIndexOperator(filter)}\\`.`,\n      );\n    }\n\n    const filterType: \"eq\" | \"gt\" | \"lt\" =\n      filter.type == \"Gt\" || filter.type == \"Gte\"\n        ? \"gt\"\n        : filter.type == \"Lt\" || filter.type == \"Lte\"\n          ? \"lt\"\n          : \"eq\";\n\n    switch (`${state}|${filterType}`) {\n      // Allow to operate on the current indexed field\n      case \"eq|eq\":\n      case \"eq|gt\":\n      case \"eq|lt\":\n        if (filter.fieldPath === fields[fieldIndex]) {\n          fieldIndex += 1;\n          state = filterType;\n          continue;\n        }\n        throw new Error(\n          `Incorrect field used in \\`withIndex\\`, ` +\n            `expected \"${fields[fieldIndex]}\", got \"${filter.fieldPath}\"`,\n        );\n\n      // Allow to operate on the previous field (gt and lt must operate on same field)\n      case \"lt|gt\":\n      case \"gt|lt\":\n        if (fieldIndex > 0 && filter.fieldPath === fields[fieldIndex - 1]) {\n          state = \"done\";\n          continue;\n        }\n        throw new Error(\n          `Incorrect field used in \\`withIndex\\`, ` +\n            `\\`.gt\\` and \\`.lt\\` must operate on the same field, ` +\n            `expected \"${fields[fieldIndex - 1]}\", got \"${filter.fieldPath}\"`,\n        );\n\n      default:\n        throw new Error(\n          `Incorrect operator used in \\`withIndex\\`, ` +\n            `cannot chain \\`.${filter.type.toLowerCase()}()\\` ` +\n            `after \\`.${source.range[filterIndex - 1].type.toLowerCase()}()\\``,\n        );\n    }\n  }\n}\n\nexport function printIndexOperator(filter: SerializedRangeExpression) {\n  return `.${filter.type.toLowerCase()}(${filter.fieldPath}, ${JSON.stringify(filter.value)})`;\n}\n\nexport function validateFieldNames(validator: ValidatorJSON) {\n  if (validator.type === \"object\") {\n    Object.keys(validator.value).forEach((fieldName) => {\n      if (!isValidIdentifier(fieldName)) {\n        throw new Error(\n          `Field names must be valid identifiers, got \"${fieldName}\"`,\n        );\n      }\n    });\n  }\n\n  if (validator.type === \"union\") {\n    validator.value.forEach(validateFieldNames);\n  }\n}\n\nexport function isValidIdentifier(name: string) {\n  return /(^_(id|creationTime)$)|^[a-zA-Z][a-zA-Z0-9_]*$/.test(name);\n}\n\nexport type ObjectFieldType = { fieldType: ValidatorJSON; optional: boolean };\n\nexport type ValidatorJSON =\n  | {\n      type: \"null\";\n    }\n  | { type: \"number\" }\n  | { type: \"bigint\" }\n  | { type: \"commitTs\" }\n  | { type: \"boolean\" }\n  | { type: \"string\" }\n  | { type: \"bytes\" }\n  | { type: \"any\" }\n  | {\n      type: \"literal\";\n      value: JSONValue;\n    }\n  | { type: \"id\"; tableName: string }\n  | { type: \"array\"; value: ValidatorJSON }\n  | { type: \"object\"; value: Record<string, ObjectFieldType> }\n  | { type: \"record\"; keys: ValidatorJSON; values: ObjectFieldType }\n  | { type: \"union\"; value: ValidatorJSON[] };\n\nexport function validateValidator(validator: ValidatorJSON, value: any) {\n  switch (validator.type) {\n    case \"null\": {\n      if (value !== null) {\n        throw new Error(`Validator error: Expected \\`null\\`, got \\`${value}\\``);\n      }\n      return;\n    }\n    case \"number\": {\n      if (typeof value !== \"number\") {\n        throw new Error(\n          `Validator error: Expected \\`number\\`, got \\`${value}\\``,\n        );\n      }\n      return;\n    }\n    case \"bigint\": {\n      if (typeof value !== \"bigint\") {\n        throw new Error(\n          `Validator error: Expected \\`bigint\\`, got \\`${value}\\``,\n        );\n      }\n      return;\n    }\n    case \"commitTs\": {\n      if (\n        typeof value !== \"bigint\" &&\n        !(value instanceof CommitTsPlaceholder)\n      ) {\n        throw new Error(\n          `Validator error: Expected \\`v.commitTs()\\`, got \\`${value}\\``,\n        );\n      }\n      return;\n    }\n    case \"boolean\": {\n      if (typeof value !== \"boolean\") {\n        throw new Error(\n          `Validator error: Expected \\`boolean\\`, got \\`${value}\\``,\n        );\n      }\n      return;\n    }\n    case \"string\": {\n      if (typeof value !== \"string\") {\n        throw new Error(\n          `Validator error: Expected \\`string\\`, got \\`${value}\\``,\n        );\n      }\n      return;\n    }\n    case \"bytes\": {\n      if (!(value instanceof ArrayBuffer)) {\n        throw new Error(\n          `Validator error: Expected \\`ArrayBuffer\\`, got \\`${value}\\``,\n        );\n      }\n      return;\n    }\n    case \"any\": {\n      return;\n    }\n    case \"literal\": {\n      if (value !== validator.value) {\n        throw new Error(\n          `Validator error: Expected \\`${\n            validator.value as any\n          }\\`, got \\`${value}\\``,\n        );\n      }\n      return;\n    }\n    case \"id\": {\n      if (typeof value !== \"string\") {\n        throw new Error(\n          `Validator error: Expected \\`string\\`, got \\`${value}\\``,\n        );\n      }\n      if (tableNameFromId(value) !== validator.tableName) {\n        throw new Error(\n          `Validator error: Expected ID for table \"${validator.tableName}\", got \\`${value}\\``,\n        );\n      }\n      return;\n    }\n    case \"array\": {\n      if (!Array.isArray(value)) {\n        throw new Error(\n          `Validator error: Expected \\`Array\\`, got \\`${value}\\``,\n        );\n      }\n      for (const v of value) {\n        validateValidator(validator.value, v);\n      }\n      return;\n    }\n    case \"union\": {\n      let isValid = false;\n      for (const v of validator.value) {\n        try {\n          validateValidator(v, value);\n          isValid = true;\n          break;\n        } catch {\n          // Ignore\n        }\n      }\n      if (!isValid) {\n        throw new Error(\n          `Validator error: Expected one of ${validator.value.map((v) => v.type).join(\", \")}, got \\`${JSON.stringify(convexToJson(value))}\\``,\n        );\n      }\n      return;\n    }\n    case \"object\": {\n      if (typeof value !== \"object\") {\n        throw new Error(\n          `Validator error: Expected \\`object\\`, got \\`${value}\\``,\n        );\n      }\n      if (!isSimpleObject(value)) {\n        throw new Error(\n          `Validator error: Expected a plain old JavaScript \\`object\\`, got \\`${value}\\``,\n        );\n      }\n      for (const [k, { fieldType, optional }] of Object.entries(\n        validator.value,\n      )) {\n        if (value[k] === undefined) {\n          if (!optional) {\n            throw new Error(\n              `Validator error: Missing required field \\`${k}\\` in object`,\n            );\n          }\n        } else {\n          validateValidator(fieldType, value[k]);\n        }\n      }\n      for (const k of Object.keys(value)) {\n        if (validator.value[k] === undefined) {\n          throw new Error(\n            `Validator error: Unexpected field \\`${k}\\` in object`,\n          );\n        }\n      }\n      return;\n    }\n    case \"record\": {\n      if (\n        value === null ||\n        typeof value !== \"object\" ||\n        !isSimpleObject(value)\n      ) {\n        throw new Error(\n          `Validator error: Expected a plain old JavaScript \\`object\\` for a record, got \\`${value}\\``,\n        );\n      }\n      for (const [k, fieldValue] of Object.entries(value)) {\n        validateValidator(validator.keys, k);\n        if (fieldValue !== undefined) {\n          validateValidator(validator.values.fieldType, fieldValue);\n        }\n      }\n      return;\n    }\n    default: {\n      const unknown: never = validator;\n      throw new Error(\n        `The test kernel cannot check a validator of type \\`${(unknown as { type: string }).type}\\`.`,\n      );\n    }\n  }\n}\n\nexport const JWT_CLAIM_BY_IDENTITY_ATTRIBUTE: Record<string, string> = {\n  subject: \"sub\",\n  issuer: \"iss\",\n  name: \"name\",\n  givenName: \"given_name\",\n  familyName: \"family_name\",\n  nickname: \"nickname\",\n  preferredUsername: \"preferred_username\",\n  profileUrl: \"profile\",\n  pictureUrl: \"picture\",\n  email: \"email\",\n  emailVerified: \"email_verified\",\n  gender: \"gender\",\n  birthday: \"birthdate\",\n  timezone: \"zoneinfo\",\n  language: \"locale\",\n  phoneNumber: \"phone_number\",\n  phoneNumberVerified: \"phone_number_verified\",\n  address: \"address\",\n  updatedAt: \"updated_at\",\n};\n\nexport function base64UrlEncode(value: string) {\n  return base64UrlEncodeBytes(new TextEncoder().encode(value));\n}\n\nexport function base64UrlEncodeBytes(bytes: Uint8Array) {\n  let binary = \"\";\n  for (const byte of bytes) {\n    binary += String.fromCharCode(byte);\n  }\n  return btoa(binary)\n    .replace(/\\+/g, \"-\")\n    .replace(/\\//g, \"_\")\n    .replace(/=+$/, \"\");\n}\n\n// Builds the token `withIdentity` pretends the request was authenticated with.\n// Real tokens are signed by an identity provider; this one is unsecured\n// (`\"alg\": \"none\"`, empty signature).\nexport function createTestJwt(identity: Record<string, any>) {\n  const claims: Record<string, any> = Object.create(null);\n  for (const [attribute, value] of Object.entries(identity)) {\n    if (value === undefined || attribute === \"tokenIdentifier\") {\n      continue;\n    }\n    // Custom claims are used as is, known attributes use their claim name.\n    const claimName = Object.hasOwn(JWT_CLAIM_BY_IDENTITY_ATTRIBUTE, attribute)\n      ? JWT_CLAIM_BY_IDENTITY_ATTRIBUTE[attribute]\n      : attribute;\n    claims[claimName] = value;\n  }\n  // The identity provider always determines who the user is.\n  claims.iss = identity.issuer;\n  claims.sub = identity.subject;\n  const header = base64UrlEncode(JSON.stringify({ alg: \"none\", typ: \"JWT\" }));\n  const payload = base64UrlEncode(JSON.stringify(claims));\n  return `${header}.${payload}.`;\n}\n\n// Limits the backend puts on tokens from `ctx.auth.signJwt`.\nexport function parseArgs(\n  args: Record<string, Value> | undefined,\n): Record<string, Value> {\n  if (args === undefined) {\n    return {};\n  }\n  if (!isSimpleObject(args)) {\n    throw new Error(\n      `The arguments to a Convex function must be an object. Received: ${\n        args as any\n      }`,\n    );\n  }\n  return args;\n}\n\nexport function validateFunctionArgs(\n  argsValidator: ValidatorJSON,\n  args: any,\n  functionPath: FunctionPath,\n  allowPendingValues: boolean,\n) {\n  if (!allowPendingValues && hasPendingValues(args)) {\n    throw new Error(\n      `Invalid arguments for \"${functionPath.udfPath}\": an unresolved ` +\n        `placeholder value can only be passed to a query or mutation ` +\n        `called from a mutation`,\n    );\n  }\n  validateValidator(argsValidator, resolvePendingValues(args));\n}\n\nexport function validateReturnValue(\n  returnsValidator: ValidatorJSON | null,\n  result: any,\n  functionType: \"query\" | \"mutation\" | \"action\",\n  functionPath: FunctionPath,\n) {\n  if (returnsValidator !== null) {\n    try {\n      validateValidator(returnsValidator, resolvePendingValues(result));\n    } catch (e) {\n      throw new Error(\n        `Return value validation failed for ${functionType} \"${functionPath.udfPath}\":\\n${(e as Error).message}`,\n        { cause: e },\n      );\n    }\n  }\n}\n\nexport function createFunctionHandle(functionPath: FunctionPath) {\n  return `function://${functionPath.componentPath};${functionPath.udfPath}`;\n}\n\nexport function parseFunctionHandle(handle: string) {\n  const [componentPath, udfPath] = handle.split(\"function://\")[1].split(\";\");\n  return { componentPath, udfPath };\n}\nexport function simpleHash(string: string) {\n  let hash = 0;\n  for (let i = 0; i < string.length; i++) {\n    const char = string.charCodeAt(i);\n    hash = (hash << 5) - hash + char;\n    hash = hash & hash; // Convert to 32bit integer\n  }\n  return hash;\n}\n"],"mappings":";;AAoFA,SAAgB,gBAAgB,IAAY;CAC1C,MAAM,QAAQ,GAAG,MAAM,SAAS;CAChC,IAAI,CAAC,SAAS,MAAM,EAAE,CAAC,WAAW,GAAG,QACnC,OAAO;CAET,OAAO,GAAG,MAAM,MAAM,EAAE,CAAC,MAAM;AACjC;AACA,SAAgB,2BAA2B,QAAiB;CAC1D,IACE,OAAO,WAAW,YAClB,WAAW,QACX,OAAO,IAAI,aAAa,KAAK,UAC7B,OAAQ,OAA6B,SAAS,UAE9C,IAAI;EACF,OAA8B,OAAO,aACnC,KAAK,MAAO,OAA4B,IAAI,CAC9C;CACF,QAAQ,CAER;CAEF,OAAO;AACT;AAEA,SAAgB,eAAe,OAAgB;CAC7C,MAAM,WAAW,OAAO,UAAU;CAClC,MAAM,YAAY,OAAO,eAAe,KAAK;CAC7C,MAAM,WACJ,cAAc,QACd,cAAc,OAAO,aAGrB,WAAW,aAAa,SAAS;CACnC,OAAO,YAAY;AACrB;AAGA,MAAa,gBAAgB,MAAM,MAAM;AAEzC,SAAgB,iBAAiB,OAAuB;CACtD,IAAI,iBAAiB,qBACnB,OAAO;CAET,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,MAAM,KAAK,gBAAgB;CAEpC,IAAI,UAAU,QAAQ,UAAU,KAAA,KAAa,eAAe,KAAK,GAC/D,OAAO,OAAO,OAAO,KAAK,CAAC,CAAC,KAAK,gBAAgB;CAEnD,OAAO;AACT;AAGA,SAAgB,qBAAqB,OAAqB;CACxD,OAAO,mBAAmB,OAAO,aAAa;AAChD;AAGA,SAAgB,uBACd,OACA,UACG;CACH,OAAO,mBAAmB,OAAO,QAAQ;AAC3C;AAEA,SAAgB,mBACd,OACA,UACG;CACH,IAAI,CAAC,iBAAiB,KAAK,GACzB,OAAO;CAET,IAAI,iBAAiB,qBACnB,OAAO;CAET,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,MAAM,KAAK,MAAM,mBAAmB,GAAG,QAAQ,CAAC;CAEzD,OAAO,OAAO,YACZ,OAAO,QAAQ,KAAe,CAAC,CAAC,KAAK,CAAC,GAAG,OAAO,CAC9C,GACA,mBAAmB,GAAG,QAAQ,CAChC,CAAC,CACH;AACF;AAEA,SAAgB,kBAAkB,WAAmB,UAAe;CAClE,MAAM,YAAY,UAAU,MAAM,GAAG;CACrC,IAAI,SAA4B;CAChC,KAAK,MAAM,KAAK,WACd,SACE,WAAW,KAAA,KAAa,WAAW,QAAQ,eAAe,MAAM,IAC3D,OAAe,KAChB,KAAA;CAER,OAAO,WAAW,KAAA,IAAY,KAAA,IAAY,qBAAqB,MAAM;AACvE;AAEA,SAAgB,eACd,UACA,QACmB;CACnB,IAAI,OAAO,QAAQ,KAAA,GACjB,OACE,cACE,eAAe,UAAU,OAAO,IAAI,EAAE,GACtC,eAAe,UAAU,OAAO,IAAI,EAAE,CACxC,MAAM;CAGV,IAAI,OAAO,SAAS,KAAA,GAClB,OACE,cACE,eAAe,UAAU,OAAO,KAAK,EAAE,GACvC,eAAe,UAAU,OAAO,KAAK,EAAE,CACzC,MAAM;CAGV,IAAI,OAAO,SAAS,KAAA,GAClB,OAAO,OAAO,KAAK,OAAO,UAAe,eAAe,UAAU,KAAK,CAAC;CAE1E,IAAI,OAAO,QAAQ,KAAA,GACjB,OAAO,OAAO,IAAI,MAAM,UAAe,eAAe,UAAU,KAAK,CAAC;CAExE,IAAI,OAAO,SAAS,KAAA,GAClB,OAAO,CAAC,eAAe,UAAU,OAAO,IAAI;CAE9C,IAAI,OAAO,QAAQ,KAAA,GACjB,OACE,eAAe,UAAU,OAAO,IAAI,EAAE,IACtC,eAAe,UAAU,OAAO,IAAI,EAAE;CAG1C,IAAI,OAAO,SAAS,KAAA,GAClB,OACE,eAAe,UAAU,OAAO,KAAK,EAAE,KACvC,eAAe,UAAU,OAAO,KAAK,EAAE;CAG3C,IAAI,OAAO,QAAQ,KAAA,GACjB,OACE,eAAe,UAAU,OAAO,IAAI,EAAE,IACtC,eAAe,UAAU,OAAO,IAAI,EAAE;CAG1C,IAAI,OAAO,SAAS,KAAA,GAClB,OACE,eAAe,UAAU,OAAO,KAAK,EAAE,KACvC,eAAe,UAAU,OAAO,KAAK,EAAE;CAG3C,IAAI,OAAO,SAAS,KAAA,GAClB,OACG,eAAe,UAAU,OAAO,KAAK,EAAE,IACvC,eAAe,UAAU,OAAO,KAAK,EAAE;CAG5C,IAAI,OAAO,SAAS,KAAA,GAClB,OACG,eAAe,UAAU,OAAO,KAAK,EAAE,IACvC,eAAe,UAAU,OAAO,KAAK,EAAE;CAG5C,IAAI,OAAO,SAAS,KAAA,GAClB,OACG,eAAe,UAAU,OAAO,KAAK,EAAE,IACvC,eAAe,UAAU,OAAO,KAAK,EAAE;CAG5C,IAAI,OAAO,SAAS,KAAA,GAClB,OACG,eAAe,UAAU,OAAO,KAAK,EAAE,IACvC,eAAe,UAAU,OAAO,KAAK,EAAE;CAG5C,IAAI,OAAO,SAAS,KAAA,GAClB,OACG,eAAe,UAAU,OAAO,KAAK,EAAE,IACvC,eAAe,UAAU,OAAO,KAAK,EAAE;CAG5C,IAAI,OAAO,WAAW,KAAA,GACpB,OAAO,kBAAkB,OAAO,QAAQ,QAAQ;CAElD,IAAI,OAAO,aAAa,KAAA,GACtB,OAAO,mBAAmB,OAAO,QAAQ;CAE3C,MAAM,IAAI,MAAM,oBAAoB,KAAK,UAAU,MAAM,GAAG;AAC9D;AAEA,SAAgB,oBACd,UACA,MACA;CACA,MAAM,SAAS,kBAAkB,KAAK,WAAW,QAAQ;CACzD,MAAM,QAAQ,mBAAmB,KAAK,KAAK;CAC3C,QAAQ,KAAK,MAAb;EACE,KAAK,MACH,OAAO,cAAc,QAAQ,KAAK,MAAM;EAC1C,KAAK,MACH,OAAO,cAAc,QAAQ,KAAK,IAAI;EACxC,KAAK,OACH,OAAO,cAAc,QAAQ,KAAK,KAAK;EACzC,KAAK,MACH,OAAO,cAAc,QAAQ,KAAK,IAAI;EACxC,KAAK,OACH,OAAO,cAAc,QAAQ,KAAK,KAAK;CAC3C;AACF;AAGA,SAAgB,cAAc,OAAkB;CAC9C,IAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,gBAAgB,OACjE;CAEF,OAAO,aAAa,KAAK;AAC3B;AAGA,SAAgB,mBAAmB,OAAkB;CACnD,MAAM,iBAAiB,cAAc,KAAK;CAC1C,OAAO,mBAAmB,KAAA,IACtB,KAAA,IACA,qBAAqB,cAAc;AACzC;AAOA,SAAgB,6BACd,QACA,QACA;CACA,IAAI,aAAa;CACjB,IAAI,QAAqC;CACzC,KAAK,MAAM,CAAC,aAAa,WAAW,OAAO,MAAM,QAAQ,GAAG;EAC1D,IAAI,UAAU,QACZ,MAAM,IAAI,MACR,iIAEW,mBAAmB,MAAM,EAAE,IACxC;EAGF,MAAM,aACJ,OAAO,QAAQ,QAAQ,OAAO,QAAQ,QAClC,OACA,OAAO,QAAQ,QAAQ,OAAO,QAAQ,QACpC,OACA;EAER,QAAQ,GAAG,MAAM,GAAG,cAApB;GAEE,KAAK;GACL,KAAK;GACL,KAAK;IACH,IAAI,OAAO,cAAc,OAAO,aAAa;KAC3C,cAAc;KACd,QAAQ;KACR;IACF;IACA,MAAM,IAAI,MACR,oDACe,OAAO,YAAY,UAAU,OAAO,UAAU,EAC/D;GAGF,KAAK;GACL,KAAK;IACH,IAAI,aAAa,KAAK,OAAO,cAAc,OAAO,aAAa,IAAI;KACjE,QAAQ;KACR;IACF;IACA,MAAM,IAAI,MACR,wGAEe,OAAO,aAAa,GAAG,UAAU,OAAO,UAAU,EACnE;GAEF,SACE,MAAM,IAAI,MACR,6DACqB,OAAO,KAAK,YAAY,EAAE,gBACjC,OAAO,MAAM,cAAc,EAAE,CAAC,KAAK,YAAY,EAAE,KACjE;EACJ;CACF;AACF;AAEA,SAAgB,mBAAmB,QAAmC;CACpE,OAAO,IAAI,OAAO,KAAK,YAAY,EAAE,GAAG,OAAO,UAAU,IAAI,KAAK,UAAU,OAAO,KAAK,EAAE;AAC5F;AAEA,SAAgB,mBAAmB,WAA0B;CAC3D,IAAI,UAAU,SAAS,UACrB,OAAO,KAAK,UAAU,KAAK,CAAC,CAAC,SAAS,cAAc;EAClD,IAAI,CAAC,kBAAkB,SAAS,GAC9B,MAAM,IAAI,MACR,+CAA+C,UAAU,EAC3D;CAEJ,CAAC;CAGH,IAAI,UAAU,SAAS,SACrB,UAAU,MAAM,QAAQ,kBAAkB;AAE9C;AAEA,SAAgB,kBAAkB,MAAc;CAC9C,OAAO,iDAAiD,KAAK,IAAI;AACnE;AAyBA,SAAgB,kBAAkB,WAA0B,OAAY;CACtE,QAAQ,UAAU,MAAlB;EACE,KAAK;GACH,IAAI,UAAU,MACZ,MAAM,IAAI,MAAM,6CAA6C,MAAM,GAAG;GAExE;EAEF,KAAK;GACH,IAAI,OAAO,UAAU,UACnB,MAAM,IAAI,MACR,+CAA+C,MAAM,GACvD;GAEF;EAEF,KAAK;GACH,IAAI,OAAO,UAAU,UACnB,MAAM,IAAI,MACR,+CAA+C,MAAM,GACvD;GAEF;EAEF,KAAK;GACH,IACE,OAAO,UAAU,YACjB,EAAE,iBAAiB,sBAEnB,MAAM,IAAI,MACR,qDAAqD,MAAM,GAC7D;GAEF;EAEF,KAAK;GACH,IAAI,OAAO,UAAU,WACnB,MAAM,IAAI,MACR,gDAAgD,MAAM,GACxD;GAEF;EAEF,KAAK;GACH,IAAI,OAAO,UAAU,UACnB,MAAM,IAAI,MACR,+CAA+C,MAAM,GACvD;GAEF;EAEF,KAAK;GACH,IAAI,EAAE,iBAAiB,cACrB,MAAM,IAAI,MACR,oDAAoD,MAAM,GAC5D;GAEF;EAEF,KAAK,OACH;EAEF,KAAK;GACH,IAAI,UAAU,UAAU,OACtB,MAAM,IAAI,MACR,+BACE,UAAU,MACX,YAAY,MAAM,GACrB;GAEF;EAEF,KAAK;GACH,IAAI,OAAO,UAAU,UACnB,MAAM,IAAI,MACR,+CAA+C,MAAM,GACvD;GAEF,IAAI,gBAAgB,KAAK,MAAM,UAAU,WACvC,MAAM,IAAI,MACR,2CAA2C,UAAU,UAAU,WAAW,MAAM,GAClF;GAEF;EAEF,KAAK;GACH,IAAI,CAAC,MAAM,QAAQ,KAAK,GACtB,MAAM,IAAI,MACR,8CAA8C,MAAM,GACtD;GAEF,KAAK,MAAM,KAAK,OACd,kBAAkB,UAAU,OAAO,CAAC;GAEtC;EAEF,KAAK,SAAS;GACZ,IAAI,UAAU;GACd,KAAK,MAAM,KAAK,UAAU,OACxB,IAAI;IACF,kBAAkB,GAAG,KAAK;IAC1B,UAAU;IACV;GACF,QAAQ,CAER;GAEF,IAAI,CAAC,SACH,MAAM,IAAI,MACR,oCAAoC,UAAU,MAAM,KAAK,MAAM,EAAE,IAAI,CAAC,CAAC,KAAK,IAAI,EAAE,UAAU,KAAK,UAAU,aAAa,KAAK,CAAC,EAAE,GAClI;GAEF;EACF;EACA,KAAK;GACH,IAAI,OAAO,UAAU,UACnB,MAAM,IAAI,MACR,+CAA+C,MAAM,GACvD;GAEF,IAAI,CAAC,eAAe,KAAK,GACvB,MAAM,IAAI,MACR,sEAAsE,MAAM,GAC9E;GAEF,KAAK,MAAM,CAAC,GAAG,EAAE,WAAW,eAAe,OAAO,QAChD,UAAU,KACZ,GACE,IAAI,MAAM,OAAO,KAAA,GACX;QAAA,CAAC,UACH,MAAM,IAAI,MACR,6CAA6C,EAAE,aACjD;GAAA,OAGF,kBAAkB,WAAW,MAAM,EAAE;GAGzC,KAAK,MAAM,KAAK,OAAO,KAAK,KAAK,GAC/B,IAAI,UAAU,MAAM,OAAO,KAAA,GACzB,MAAM,IAAI,MACR,uCAAuC,EAAE,aAC3C;GAGJ;EAEF,KAAK;GACH,IACE,UAAU,QACV,OAAO,UAAU,YACjB,CAAC,eAAe,KAAK,GAErB,MAAM,IAAI,MACR,mFAAmF,MAAM,GAC3F;GAEF,KAAK,MAAM,CAAC,GAAG,eAAe,OAAO,QAAQ,KAAK,GAAG;IACnD,kBAAkB,UAAU,MAAM,CAAC;IACnC,IAAI,eAAe,KAAA,GACjB,kBAAkB,UAAU,OAAO,WAAW,UAAU;GAE5D;GACA;EAEF,SAEE,MAAM,IAAI,MACR,sDAAuDA,UAA6B,KAAK,IAC3F;CAEJ;AACF;AAEA,MAAa,kCAA0D;CACrE,SAAS;CACT,QAAQ;CACR,MAAM;CACN,WAAW;CACX,YAAY;CACZ,UAAU;CACV,mBAAmB;CACnB,YAAY;CACZ,YAAY;CACZ,OAAO;CACP,eAAe;CACf,QAAQ;CACR,UAAU;CACV,UAAU;CACV,UAAU;CACV,aAAa;CACb,qBAAqB;CACrB,SAAS;CACT,WAAW;AACb;AAEA,SAAgB,gBAAgB,OAAe;CAC7C,OAAO,qBAAqB,IAAI,YAAY,CAAC,CAAC,OAAO,KAAK,CAAC;AAC7D;AAEA,SAAgB,qBAAqB,OAAmB;CACtD,IAAI,SAAS;CACb,KAAK,MAAM,QAAQ,OACjB,UAAU,OAAO,aAAa,IAAI;CAEpC,OAAO,KAAK,MAAM,CAAC,CAChB,QAAQ,OAAO,GAAG,CAAC,CACnB,QAAQ,OAAO,GAAG,CAAC,CACnB,QAAQ,OAAO,EAAE;AACtB;AAKA,SAAgB,cAAc,UAA+B;CAC3D,MAAM,SAA8B,OAAO,OAAO,IAAI;CACtD,KAAK,MAAM,CAAC,WAAW,UAAU,OAAO,QAAQ,QAAQ,GAAG;EACzD,IAAI,UAAU,KAAA,KAAa,cAAc,mBACvC;EAGF,MAAM,YAAY,OAAO,OAAO,iCAAiC,SAAS,IACtE,gCAAgC,aAChC;EACJ,OAAO,aAAa;CACtB;CAEA,OAAO,MAAM,SAAS;CACtB,OAAO,MAAM,SAAS;CAGtB,OAAO,GAFQ,gBAAgB,KAAK,UAAU;EAAE,KAAK;EAAQ,KAAK;CAAM,CAAC,CAE1D,EAAE,GADD,gBAAgB,KAAK,UAAU,MAAM,CAC3B,EAAE;AAC9B;AAGA,SAAgB,UACd,MACuB;CACvB,IAAI,SAAS,KAAA,GACX,OAAO,CAAC;CAEV,IAAI,CAAC,eAAe,IAAI,GACtB,MAAM,IAAI,MACR,mEACE,MAEJ;CAEF,OAAO;AACT;AAEA,SAAgB,qBACd,eACA,MACA,cACA,oBACA;CACA,IAAI,CAAC,sBAAsB,iBAAiB,IAAI,GAC9C,MAAM,IAAI,MACR,0BAA0B,aAAa,QAAQ,oGAGjD;CAEF,kBAAkB,eAAe,qBAAqB,IAAI,CAAC;AAC7D;AAEA,SAAgB,oBACd,kBACA,QACA,cACA,cACA;CACA,IAAI,qBAAqB,MACvB,IAAI;EACF,kBAAkB,kBAAkB,qBAAqB,MAAM,CAAC;CAClE,SAAS,GAAG;EACV,MAAM,IAAI,MACR,sCAAsC,aAAa,IAAI,aAAa,QAAQ,MAAO,EAAY,WAC/F,EAAE,OAAO,EAAE,CACb;CACF;AAEJ;AAEA,SAAgB,qBAAqB,cAA4B;CAC/D,OAAO,cAAc,aAAa,cAAc,GAAG,aAAa;AAClE;AAEA,SAAgB,oBAAoB,QAAgB;CAClD,MAAM,CAAC,eAAe,WAAW,OAAO,MAAM,aAAa,CAAC,CAAC,EAAE,CAAC,MAAM,GAAG;CACzE,OAAO;EAAE;EAAe;CAAQ;AAClC;AACA,SAAgB,WAAW,QAAgB;CACzC,IAAI,OAAO;CACX,KAAK,IAAI,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAK;EACtC,MAAM,OAAO,OAAO,WAAW,CAAC;EAChC,QAAQ,QAAQ,KAAK,OAAO;EAC5B,OAAO,OAAO;CAChB;CACA,OAAO;AACT"}

package/dist/internal/ReadSet.d.ts

@@ -0,0 +1,55 @@
+import { type Value } from "convex/values";
+import type { DocumentId, SerializedRangeExpression, StoredDocument } from "./KernelValues.js";
+/**
+ * A row's position in an interval's order: its value at each of the interval's
+ * fields.
+ */
+export type Key = ReadonlyArray<Value | undefined>;
+/**
+ * A read of one document by ID. It records the document's absence as well as
+ * its presence, so a commit that creates the document invalidates it.
+ */
+export interface DocumentRead {
+    readonly kind: "document";
+    readonly componentPath: string;
+    readonly id: DocumentId;
+}
+/**
+ * A read of an ordered interval of one table.
+ *
+ * `fields` is the sort key: an index's fields, then the tie-breakers
+ * `_creationTime` and `_id`. `range` is the index range expression, whose `Gt`
+ * and `Lt` bounds are exclusive and `Gte` and `Lte` inclusive. `after` is an
+ * exclusive start in `order`, a page's cursor. `through` is how far the query
+ * examined, inclusive: nothing yet, up to a key, or to the end of the range. An
+ * empty result reads to the end, so it still covers an insert into the range.
+ *
+ * Only the attempt that owns the read advances `through`.
+ */
+export interface IntervalRead {
+    readonly kind: "interval";
+    readonly componentPath: string;
+    readonly table: string;
+    readonly fields: ReadonlyArray<string>;
+    readonly order: "asc" | "desc";
+    readonly range: ReadonlyArray<SerializedRangeExpression>;
+    readonly after: Key | null;
+    through: Key | "end" | null;
+}
+export type Read = DocumentRead | IntervalRead;
+/**
+ * Where `doc` sorts against `key` in the interval's order.
+ */
+export declare const compareToKey: (fields: ReadonlyArray<string>, order: "asc" | "desc", doc: StoredDocument, key: Key) => number;
+export declare const keyOf: (fields: ReadonlyArray<string>, doc: StoredDocument) => Key;
+/**
+ * Whether a commit's change to one document invalidates `read`: it wrote the
+ * document read by ID, or the document entered or left the interval.
+ */
+export declare const covers: (read: Read, change: {
+    readonly componentPath: string;
+    readonly id: DocumentId;
+    readonly before: StoredDocument | null;
+    readonly after: StoredDocument | null;
+}) => boolean;
+//# sourceMappingURL=ReadSet.d.ts.map

package/dist/internal/ReadSet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReadSet.d.ts","sourceRoot":"","sources":["../../src/internal/ReadSet.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,KAAK,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EACV,UAAU,EACV,yBAAyB,EACzB,cAAc,EACf,MAAM,mBAAmB,CAAC;AAO3B;;;GAGG;AACH,MAAM,MAAM,GAAG,GAAG,aAAa,CAAC,KAAK,GAAG,SAAS,CAAC,CAAC;AAEnD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,yBAAyB,CAAC,CAAC;IACzD,QAAQ,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,GAAG,GAAG,KAAK,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,MAAM,IAAI,GAAG,YAAY,GAAG,YAAY,CAAC;AAE/C;;GAEG;AACH,eAAO,MAAM,YAAY,WACf,aAAa,CAAC,MAAM,CAAC,SACtB,KAAK,GAAG,MAAM,OAChB,cAAc,OACd,GAAG,KACP,MAUF,CAAC;AAEF,eAAO,MAAM,KAAK,WACR,aAAa,CAAC,MAAM,CAAC,OACxB,cAAc,KAClB,GAA2D,CAAC;AAU/D;;;GAGG;AACH,eAAO,MAAM,MAAM,SACX,IAAI,UACF;IACN,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;CACvC,KACA,OASF,CAAC"}

package/dist/internal/ReadSet.js

@@ -0,0 +1,29 @@
+import { evaluateFieldPath, evaluateRangeFilter, tableNameFromId } from "./KernelValues.js";
+import { compareValues } from "convex/values";
+//#region src/internal/ReadSet.ts
+/**
+* Where `doc` sorts against `key` in the interval's order.
+*/
+const compareToKey = (fields, order, doc, key) => {
+	const direction = order === "asc" ? 1 : -1;
+	for (let i = 0; i < fields.length; i++) {
+		const cmp = compareValues(evaluateFieldPath(fields[i], doc), key[i]);
+		if (cmp !== 0) return cmp * direction;
+	}
+	return 0;
+};
+const keyOf = (fields, doc) => fields.map((field) => evaluateFieldPath(field, doc));
+const inInterval = (read, doc) => read.through !== null && read.range.every((filter) => evaluateRangeFilter(doc, filter)) && (read.after === null || compareToKey(read.fields, read.order, doc, read.after) > 0) && (read.through === "end" || compareToKey(read.fields, read.order, doc, read.through) <= 0);
+/**
+* Whether a commit's change to one document invalidates `read`: it wrote the
+* document read by ID, or the document entered or left the interval.
+*/
+const covers = (read, change) => {
+	if (read.componentPath !== change.componentPath) return false;
+	if (read.kind === "document") return read.id === change.id;
+	return tableNameFromId(change.id) === read.table && [change.before, change.after].some((doc) => doc !== null && inInterval(read, doc));
+};
+//#endregion
+export { compareToKey, covers, keyOf };
+
+//# sourceMappingURL=ReadSet.js.map

package/dist/internal/ReadSet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReadSet.js","names":[],"sources":["../../src/internal/ReadSet.ts"],"sourcesContent":["import { compareValues, type Value } from \"convex/values\";\nimport type {\n  DocumentId,\n  SerializedRangeExpression,\n  StoredDocument,\n} from \"./KernelValues.js\";\nimport {\n  evaluateFieldPath,\n  evaluateRangeFilter,\n  tableNameFromId,\n} from \"./KernelValues.js\";\n\n/**\n * A row's position in an interval's order: its value at each of the interval's\n * fields.\n */\nexport type Key = ReadonlyArray<Value | undefined>;\n\n/**\n * A read of one document by ID. It records the document's absence as well as\n * its presence, so a commit that creates the document invalidates it.\n */\nexport interface DocumentRead {\n  readonly kind: \"document\";\n  readonly componentPath: string;\n  readonly id: DocumentId;\n}\n\n/**\n * A read of an ordered interval of one table.\n *\n * `fields` is the sort key: an index's fields, then the tie-breakers\n * `_creationTime` and `_id`. `range` is the index range expression, whose `Gt`\n * and `Lt` bounds are exclusive and `Gte` and `Lte` inclusive. `after` is an\n * exclusive start in `order`, a page's cursor. `through` is how far the query\n * examined, inclusive: nothing yet, up to a key, or to the end of the range. An\n * empty result reads to the end, so it still covers an insert into the range.\n *\n * Only the attempt that owns the read advances `through`.\n */\nexport interface IntervalRead {\n  readonly kind: \"interval\";\n  readonly componentPath: string;\n  readonly table: string;\n  readonly fields: ReadonlyArray<string>;\n  readonly order: \"asc\" | \"desc\";\n  readonly range: ReadonlyArray<SerializedRangeExpression>;\n  readonly after: Key | null;\n  through: Key | \"end\" | null;\n}\n\nexport type Read = DocumentRead | IntervalRead;\n\n/**\n * Where `doc` sorts against `key` in the interval's order.\n */\nexport const compareToKey = (\n  fields: ReadonlyArray<string>,\n  order: \"asc\" | \"desc\",\n  doc: StoredDocument,\n  key: Key,\n): number => {\n  const direction = order === \"asc\" ? 1 : -1;\n  for (let i = 0; i < fields.length; i++) {\n    const cmp = compareValues(\n      evaluateFieldPath(fields[i]!, doc),\n      key[i] as Value,\n    );\n    if (cmp !== 0) return cmp * direction;\n  }\n  return 0;\n};\n\nexport const keyOf = (\n  fields: ReadonlyArray<string>,\n  doc: StoredDocument,\n): Key => fields.map((field) => evaluateFieldPath(field, doc));\n\nconst inInterval = (read: IntervalRead, doc: StoredDocument): boolean =>\n  read.through !== null &&\n  read.range.every((filter) => evaluateRangeFilter(doc, filter)) &&\n  (read.after === null ||\n    compareToKey(read.fields, read.order, doc, read.after) > 0) &&\n  (read.through === \"end\" ||\n    compareToKey(read.fields, read.order, doc, read.through) <= 0);\n\n/**\n * Whether a commit's change to one document invalidates `read`: it wrote the\n * document read by ID, or the document entered or left the interval.\n */\nexport const covers = (\n  read: Read,\n  change: {\n    readonly componentPath: string;\n    readonly id: DocumentId;\n    readonly before: StoredDocument | null;\n    readonly after: StoredDocument | null;\n  },\n): boolean => {\n  if (read.componentPath !== change.componentPath) return false;\n  if (read.kind === \"document\") return read.id === change.id;\n  return (\n    tableNameFromId(change.id) === read.table &&\n    [change.before, change.after].some(\n      (doc) => doc !== null && inInterval(read, doc),\n    )\n  );\n};\n"],"mappings":";;;;;;AAwDA,MAAa,gBACX,QACA,OACA,KACA,QACW;CACX,MAAM,YAAY,UAAU,QAAQ,IAAI;CACxC,KAAK,IAAI,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAK;EACtC,MAAM,MAAM,cACV,kBAAkB,OAAO,IAAK,GAAG,GACjC,IAAI,EACN;EACA,IAAI,QAAQ,GAAG,OAAO,MAAM;CAC9B;CACA,OAAO;AACT;AAEA,MAAa,SACX,QACA,QACQ,OAAO,KAAK,UAAU,kBAAkB,OAAO,GAAG,CAAC;AAE7D,MAAM,cAAc,MAAoB,QACtC,KAAK,YAAY,QACjB,KAAK,MAAM,OAAO,WAAW,oBAAoB,KAAK,MAAM,CAAC,MAC5D,KAAK,UAAU,QACd,aAAa,KAAK,QAAQ,KAAK,OAAO,KAAK,KAAK,KAAK,IAAI,OAC1D,KAAK,YAAY,SAChB,aAAa,KAAK,QAAQ,KAAK,OAAO,KAAK,KAAK,OAAO,KAAK;;;;;AAMhE,MAAa,UACX,MACA,WAMY;CACZ,IAAI,KAAK,kBAAkB,OAAO,eAAe,OAAO;CACxD,IAAI,KAAK,SAAS,YAAY,OAAO,KAAK,OAAO,OAAO;CACxD,OACE,gBAAgB,OAAO,EAAE,MAAM,KAAK,SACpC,CAAC,OAAO,QAAQ,OAAO,KAAK,CAAC,CAAC,MAC3B,QAAQ,QAAQ,QAAQ,WAAW,MAAM,GAAG,CAC/C;AAEJ"}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@gaganref/confect-test",
-  "version": "10.3.1-fork.88",
+  "version": "10.3.1-fork.89",
   "peerDependencies": {
-    "@confect/core": "npm:@gaganref/confect-core@10.3.1-fork.88",
-    "@confect/server": "npm:@gaganref/confect-server@10.3.1-fork.88",
+    "@confect/core": "npm:@gaganref/confect-core@10.3.1-fork.89",
+    "@confect/server": "npm:@gaganref/confect-server@10.3.1-fork.89",
     "convex": "^1.32.0",
     "convex-test": ">=0.0.65 <0.1.0",
     "effect": ">=4.0.0 <4.1.0"

package/src/internal/Attempt.ts

@@ -0,0 +1,185 @@
+// oxlint-disable-next-line effecttsgo/node-builtin-import -- The drain waits a real turn of the event loop. Fake timers in a test replace the global `setImmediate`, not this one.
+import { setImmediate } from "node:timers/promises";
+import type { Attempt as AttemptNumber } from "./Invocation.js";
+import * as Kernel from "./Kernel.js";
+import type { DocumentId, StoredDocument } from "./KernelValues.js";
+import { tableNameFromId } from "./KernelValues.js";
+import type * as ReadSet from "./ReadSet.js";
+
+/**
+ * Pending writes, keyed by component path, then document ID. `null` deletes.
+ */
+type Overlay = Map<string, Map<DocumentId, StoredDocument | null>>;
+
+/**
+ * How long one frame takes syscalls: those it has running, those it has
+ * started, and whether it still takes them.
+ */
+interface Life {
+  running: number;
+  started: number;
+  open: boolean;
+}
+
+/**
+ * One frame of an attempt at a query or mutation: the committed state the
+ * attempt started from, its caller's frame and its own pending writes. The
+ * outermost frame belongs to the top-level function. Each nested mutation opens
+ * a child frame, which merges into its caller's frame when it returns and is
+ * dropped when it fails. Reads belong to the whole attempt and are never
+ * dropped: a failed nested mutation's reads stay in the attempt.
+ *
+ * Each frame has its own lifetime. A frame takes reads and writes until it is
+ * closed. A mutation's frame closes once its function has returned and no
+ * syscall it started is still running, so a write a detached fiber makes after
+ * the handler settled still lands in it, as on the binary. A nested mutation's
+ * frame closes before it merges into its caller's, so no write reaches it after
+ * its writes became its caller's.
+ *
+ * A frame belongs to one invocation, which alone writes to it, so a caller's
+ * write made while its nested mutation is in flight stays the caller's.
+ * `Kernel.apply` publishes the outermost frame's writes.
+ */
+export class KernelAttempt {
+  private readonly overlay: Overlay = new Map();
+  private readonly life: Life = { running: 0, started: 0, open: true };
+  private readonly allReads: Array<ReadSet.Read>;
+
+  constructor(
+    readonly snapshot: Kernel.State,
+    readonly number: AttemptNumber = 1,
+    private readonly parent?: KernelAttempt,
+  ) {
+    this.allReads = parent?.allReads ?? [];
+  }
+
+  get reads(): ReadonlyArray<ReadSet.Read> {
+    return this.allReads;
+  }
+
+  get closed(): boolean {
+    return !this.life.open;
+  }
+
+  readDocument(componentPath: string, id: DocumentId) {
+    this.allReads.push({ kind: "document", componentPath, id });
+  }
+
+  /**
+   * Record a read of an interval. The returned function advances how far the
+   * query examined it.
+   */
+  readInterval(
+    read: Omit<ReadSet.IntervalRead, "through">,
+  ): (through: ReadSet.Key | "end") => void {
+    const interval: ReadSet.IntervalRead = { ...read, through: null };
+    this.allReads.push(interval);
+    return (through) => {
+      interval.through = through;
+    };
+  }
+
+  /**
+   * A syscall began. `end` runs when it settles.
+   */
+  begin(): () => void {
+    const life = this.life;
+    life.running++;
+    life.started++;
+    return () => {
+      life.running--;
+    };
+  }
+
+  /**
+   * Resolves once a whole turn of the event loop passes with no syscall of this
+   * frame running or started. A nested call is a syscall of its caller's frame
+   * until it has drained.
+   */
+  drained(): Promise<void> {
+    const before = this.life.started;
+    return setImmediate().then(() =>
+      this.life.running === 0 && this.life.started === before
+        ? undefined
+        : this.drained(),
+    );
+  }
+
+  close() {
+    this.life.open = false;
+  }
+
+  /**
+   * The pending writes this frame sees, from the outermost frame to this one.
+   */
+  private overlays(): Array<Overlay> {
+    return this.parent === undefined
+      ? [this.overlay]
+      : [...this.parent.overlays(), this.overlay];
+  }
+
+  get(componentPath: string, id: DocumentId): StoredDocument | null {
+    for (const overlay of this.overlays().toReversed()) {
+      const write = overlay.get(componentPath)?.get(id);
+      if (write !== undefined) return write;
+    }
+    return Kernel.get(this.snapshot, componentPath, id)?.doc ?? null;
+  }
+
+  /**
+   * The table as this frame sees it, committed rows under every pending write
+   * from the outermost frame to this one.
+   */
+  scan(componentPath: string, tableName: string): Array<StoredDocument> {
+    const ids = new Set<DocumentId>();
+    for (const row of Kernel.rows(this.snapshot, componentPath, tableName))
+      ids.add(row.doc._id);
+    for (const overlay of this.overlays())
+      for (const id of overlay.get(componentPath)?.keys() ?? [])
+        if (tableNameFromId(id) === tableName) ids.add(id);
+    const docs: Array<StoredDocument> = [];
+    for (const id of ids) {
+      const doc = this.get(componentPath, id);
+      if (doc !== null) docs.push(doc);
+    }
+    return docs;
+  }
+
+  write(componentPath: string, id: DocumentId, doc: StoredDocument | null) {
+    const writes = this.overlay.get(componentPath) ?? new Map();
+    this.overlay.set(componentPath, writes);
+    writes.set(id, doc);
+  }
+
+  /**
+   * A nested mutation begins, in a frame of its own. Dropping a failed one is
+   * forgetting it.
+   */
+  child(): KernelAttempt {
+    return new KernelAttempt(this.snapshot, this.number, this);
+  }
+
+  /**
+   * A nested mutation returned and its frame closed. Its writes become its
+   * caller's.
+   */
+  merge() {
+    if (this.parent === undefined) {
+      throw new Error("The outermost frame of an attempt has no caller.");
+    }
+    if (this.life.open) {
+      throw new Error("A nested mutation's frame merges only once closed.");
+    }
+    for (const [componentPath, writes] of this.overlay)
+      for (const [id, doc] of writes) this.parent.write(componentPath, id, doc);
+  }
+
+  /**
+   * The outermost frame's writes, for `Kernel.apply`.
+   */
+  writes(): Array<Kernel.Write> {
+    return Array.from(this.overlay, ([componentPath, writes]) =>
+      Array.from(writes, ([id, doc]) => ({ componentPath, id, doc })),
+    ).flat();
+  }
+}