@cardstack/boxel-cli 0.9.0 → 0.10.0-unstable.0

package/bundled-test-harness/assets/operations-CPvfTuY3.js

@@ -0,0 +1,766 @@
+import "./chunk-Rp0pCe6z.js";
+import { Ga as PRERENDERED_HTML_FORMATS, Ii as buildOperations, Ni as operationLabelProblem, c as getOperationsTransport, fo as assertQuery, jo as identifyCard, wo as codeRefForDef, xo as InvalidQueryError } from "./runtime-common-ClpqhbwG.js";
+import { K as realmURL, V as localId } from "./constants-CqKWhRfY.js";
+import { Y as serializeCard } from "./field-support-DdQ7XgyM.js";
+import { a as CardDef, d as FileDef, l as FieldDef, n as BaseDef } from "./card-api-Dzje0smT.js";
+//#region ../base/operations.ts
+var BASE_OPERATIONS = [
+	"read",
+	"readSource",
+	"create",
+	"update",
+	"delete",
+	"query",
+	"transform",
+	"appendContainsMany",
+	"appendLine",
+	"explain",
+	"validate",
+	"callApi"
+];
+var CARRIED_BY = {
+	read: [
+		"card",
+		"file",
+		"base"
+	],
+	readSource: [
+		"card",
+		"file",
+		"base"
+	],
+	create: ["card"],
+	update: ["card", "file"],
+	delete: ["card"],
+	query: ["card"],
+	transform: ["card"],
+	appendContainsMany: ["card"],
+	appendLine: ["file"],
+	explain: [],
+	validate: [],
+	callApi: []
+};
+var DECLARATION_ONLY = {
+	explain: ["card"],
+	validate: ["card"],
+	callApi: ["card"]
+};
+function operationsCarriedBy(family) {
+	return BASE_OPERATIONS.filter((base) => CARRIED_BY[base].includes(family));
+}
+function declarationOnlyBases(family) {
+	return BASE_OPERATIONS.filter((base) => DECLARATION_ONLY[base]?.includes(family));
+}
+var CARD_OPERATIONS = operationsCarriedBy("card");
+var FILE_OPERATIONS = operationsCarriedBy("file");
+var BASE_DEF_OPERATIONS = operationsCarriedBy("base");
+var NOT_DECLARABLE = ["readSource"];
+function isNotDeclarable(name) {
+	return NOT_DECLARABLE.includes(name);
+}
+var RESERVED_BY_INVOCATION = [
+	"atomic",
+	"on",
+	"find",
+	"parallel",
+	"serial"
+];
+function isReservedByInvocation(name) {
+	return RESERVED_BY_INVOCATION.includes(name);
+}
+var RESERVED_BY_SEARCH = ["query"];
+function isReservedBySearch(name) {
+	return RESERVED_BY_SEARCH.includes(name);
+}
+function params(key) {
+	if (typeof key !== "string" || key.length === 0) throw new Error(`params() takes the name of a param declared in the operation's \`params\` schema`);
+	return {
+		$ref: "params",
+		key
+	};
+}
+function actor(...args) {
+	if (args.length > 0) throw new Error(`actor() takes no argument; it is the caller's user id`);
+	return { $ref: "actor" };
+}
+function actorIsNotACard(what) {
+	return `${what} takes a card identity, and \`actor()\` is the caller's user id rather than a card — declare the person as a \`params\` member typed \`linkTo(…)\` and link that`;
+}
+function instance(key) {
+	assertOptionalReferenceKey("instance", key);
+	return key === void 0 ? { $ref: "instance" } : {
+		$ref: "instance",
+		key
+	};
+}
+function realmConfig(key) {
+	assertOptionalReferenceKey("realmConfig", key);
+	return key === void 0 ? { $ref: "realmConfig" } : {
+		$ref: "realmConfig",
+		key
+	};
+}
+function card(reference) {
+	if (typeof reference === "string") {
+		if (reference.length === 0) throw new Error(`card() takes a card URL or a typed reference to one`);
+		return {
+			$ref: "card",
+			value: reference
+		};
+	}
+	if (!isReferenceMarker(reference)) throw new Error(`card() takes a card URL or a typed reference to one`);
+	if (reference.$ref === "actor") throw new Error(actorIsNotACard("card()"));
+	return {
+		$ref: "card",
+		value: reference
+	};
+}
+function bxl(program, ...substitutions) {
+	if (!Array.isArray(program) || !Array.isArray(program?.raw)) throw new Error(`bxl is a template tag: write bxl\`…\` rather than calling it`);
+	if (substitutions.length > 0) throw new Error(`the bxl tag does not interpolate values; read the payload, the actor, the target and the realm's configuration inside the program with the params(), actor(), instance() and realmConfig() builtins`);
+	return { $bxl: program.raw.join("") };
+}
+function linkTo(def) {
+	if (typeof def !== "function") throw new Error(`linkTo() takes a card class (or a thunk returning one, for a class declared later in the module)`);
+	if (isDefConstructor(def) && !isSubclassOf(def, CardDef) && !isSubclassOf(def, FileDef)) throw new Error(`linkTo() takes a card or file class — a link points at something with a URL`);
+	return { $linkTo: def };
+}
+var LINK_STRATEGIES = Object.keys({
+	full: true,
+	ids: true,
+	none: true
+});
+var READ_LINK_STRATEGIES = LINK_STRATEGIES.filter((strategy) => strategy !== "none");
+var HTML_SHARINGS = Object.keys({
+	shareable: true,
+	unshareable: true
+});
+var CALL_API_METHODS = [
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE"
+];
+var operationDeclarations = Symbol.for("cardstack-operation-declarations");
+var COMMON_DECLARATION_KEYS = [
+	"base",
+	"label",
+	"params",
+	"optimistic",
+	"nonGrantable",
+	"input",
+	"transformations",
+	"output"
+];
+var CLAUSE_KEYS = {
+	transform: [
+		"append",
+		"assert",
+		"set"
+	],
+	create: ["of", "fill"],
+	update: [],
+	delete: [],
+	read: [],
+	readSource: [],
+	query: ["query"],
+	appendContainsMany: [
+		"field",
+		"item",
+		"fields"
+	],
+	appendLine: [],
+	explain: [],
+	validate: [],
+	callApi: [
+		"method",
+		"url",
+		"path",
+		"headers",
+		"query",
+		"json",
+		"graphql"
+	]
+};
+var MODIFIER_KEYS = {
+	read: ["links", "html"],
+	query: ["links", "html"]
+};
+var REQUIRED_CLAUSE = {
+	create: "of",
+	query: "query",
+	callApi: "url"
+};
+var TYPE_NAMING_KEYS = ["of"];
+var operation = function(target, key, descriptor) {
+	if (typeof key === "symbol") throw new Error(`the @operation decorator only supports string operation names, not symbols`);
+	let owner = assertOperationTarget(target, key);
+	if (isNotDeclarable(key)) throw new Error(`${declarationLabel(owner, key)}: "${key}" is a reserved operation name — a "${key}" serves the bytes stored at the def's URL, which the realm answers without reading a definition, so a declaration under this name would never be reached`);
+	if (isReservedByInvocation(key)) throw new Error(`${declarationLabel(owner, key)}: "${key}" is a member of the invocation surface — operations(instance).${key} and a batch builder's ${key} are that, so a declaration under this name would never be reached`);
+	if (isReservedBySearch(key)) throw new Error(`${declarationLabel(owner, key)}: "${key}" is a reserved operation name — it is the name a search the caller writes by hand is invoked and granted under, so a saved search needs a name of its own`);
+	assertNameAvailable(owner, key);
+	if (typeof descriptor?.initializer !== "function") throw new Error(`${declarationLabel(owner, key)}: an operation must be assigned a declaration object`);
+	let declaration = descriptor.initializer.call(owner);
+	assertValidDeclaration(owner, key, declaration);
+	recordDeclaration(owner, key, declaration);
+	return {
+		configurable: true,
+		enumerable: true,
+		writable: true,
+		value: declaration
+	};
+};
+function getOperations(classOrInstance) {
+	let owner = defConstructorFor(classOrInstance, "getOperations");
+	let operations = emptyOperationRecord();
+	for (let base of impliedOperations(owner)) operations[base] = { base };
+	return Object.assign(operations, declaredOperations(owner));
+}
+function getDeclaredOperations(classOrInstance) {
+	return declaredOperations(defConstructorFor(classOrInstance, "getDeclaredOperations"));
+}
+function impliedOperations(owner) {
+	let family = defFamily(owner);
+	if (family === "card") return CARD_OPERATIONS;
+	if (family === "file") return FILE_OPERATIONS;
+	if (family === "base") return BASE_DEF_OPERATIONS;
+	return [];
+}
+function declarableOperations(owner) {
+	let family = defFamily(owner);
+	return family ? [...impliedOperations(owner), ...declarationOnlyBases(family)] : [];
+}
+function defFamily(owner) {
+	if (isSubclassOf(owner, FieldDef)) return;
+	if (isSubclassOf(owner, CardDef)) return "card";
+	if (isSubclassOf(owner, FileDef)) return "file";
+	return "base";
+}
+function declaredOperations(owner) {
+	let levels = [];
+	let current = owner;
+	while (typeof current === "function") {
+		let declarations = ownDeclarations(current);
+		if (declarations) levels.unshift(declarations);
+		current = Object.getPrototypeOf(current);
+	}
+	return Object.assign(emptyOperationRecord(), ...levels);
+}
+function emptyOperationRecord() {
+	return Object.create(null);
+}
+function defConstructorFor(classOrInstance, reader) {
+	let owner = typeof classOrInstance === "function" ? classOrInstance : classOrInstance?.constructor;
+	if (typeof owner !== "function" || !isDefConstructor(owner)) throw new Error(`${reader}() takes a class that extends BaseDef, or an instance of one; got ${describeTarget(classOrInstance)}`);
+	return owner;
+}
+function ownDeclarations(owner) {
+	if (!hasOwn(owner, operationDeclarations)) return;
+	return owner[operationDeclarations];
+}
+function recordDeclaration(owner, key, declaration) {
+	let declarations = ownDeclarations(owner);
+	if (!declarations) {
+		declarations = Object.create(null);
+		Object.defineProperty(owner, operationDeclarations, {
+			value: declarations,
+			configurable: true,
+			enumerable: false,
+			writable: false
+		});
+	}
+	declarations[key] = declaration;
+}
+function describeTarget(value) {
+	if (value === null || value === void 0) return String(value);
+	if (typeof value === "function") return `the class ${value.name || "(anonymous)"}, which does not extend BaseDef`;
+	if (typeof value !== "object") return typeof value;
+	let owner = value.constructor;
+	return owner ? `an instance of ${owner.name || "(anonymous)"}` : "an object with no constructor";
+}
+function hasOwn(target, key) {
+	return Object.prototype.hasOwnProperty.call(target, key);
+}
+function isDefConstructor(target) {
+	return typeof target === "function" && (target === BaseDef || target.prototype instanceof BaseDef);
+}
+function isSubclassOf(target, def) {
+	return target === def || target.prototype instanceof def;
+}
+function noProgramReason(owner, base) {
+	if (base === "appendLine" || base === "appendContainsMany") return `an "${base}" operation appends to the stored file rather than running a program over a document`;
+	if (base === "update" && isSubclassOf(owner, FileDef)) return `an "update" on a file def replaces the file's content wholesale rather than transforming a document`;
+	if (base === "explain") return `an "explain" operation reports what the realm's policy decides rather than running a program over a document`;
+	if (base === "validate") return `a "validate" operation reports what the policy card compiles to rather than running a program over a document`;
+	if (base === "callApi") return `a "callApi" operation sends the request it declares rather than running a program over a document`;
+}
+function assertOperationTarget(target, key) {
+	if (!isDefConstructor(target)) throw new Error(`the @operation decorator can only be used on static properties of classes that extend BaseDef`);
+	if (isSubclassOf(target, FieldDef)) throw new Error(`${declarationLabel(target, key)}: a field has no URL of its own, so it cannot carry operations — declare this on the card that contains the field`);
+	return target;
+}
+function assertNameAvailable(owner, key) {
+	if (!(key in owner)) return;
+	if (hasOwn(declaredOperations(owner), key)) return;
+	throw new Error(`${declarationLabel(owner, key)}: "${key}" already resolves on this class, so it cannot name an operation`);
+}
+function assertValidHtmlDeclaration(label, base, value) {
+	let subject = base === "query" ? "which prerendered formats this query's results are served data-only for" : "which prerendered formats reads of this card serve data-only";
+	if (!isPlainObject(value)) throw new Error(`${label}: \`html\` must be an object naming ${subject}, by format`);
+	for (let [format, sharing] of Object.entries(value)) {
+		if (!PRERENDERED_HTML_FORMATS.includes(format)) throw new Error(`${label}: \`html\` names "${format}", which is not a prerendered format — one of ${quoteList(PRERENDERED_HTML_FORMATS)}`);
+		if (!HTML_SHARINGS.includes(sharing)) throw new Error(`${label}: \`html.${format}\` must say whether the format's prerendered HTML is served — one of ${quoteList(HTML_SHARINGS)}`);
+	}
+}
+function assertValidDeclaration(owner, key, value) {
+	let label = declarationLabel(owner, key);
+	if (!isPlainObject(value)) throw new Error(`${label}: an operation must be a declaration object`);
+	let declaration = value;
+	let base = declaration.base;
+	if (!isBaseOperationName(base)) throw new Error(`${label}: \`base\` must name the built-in behavior this operation builds on — one of ${quoteList(BASE_OPERATIONS)}`);
+	if (isNotDeclarable(base)) throw new Error(`${label}: a "${base}" operation serves the bytes stored at the def's URL, so there is nothing for a declaration to specialize or rebind`);
+	let declarable = declarableOperations(owner);
+	if (!declarable.includes(base)) throw new Error(`${label}: this def type carries only ${quoteList(declarable)}, so it cannot declare a "${base}" operation`);
+	if (base === "explain" && declaration.nonGrantable !== true) throw new Error(`${label}: an "explain" operation reports what the realm's policy decides, which is what a refusal withholds, so no policy may grant it; declare it with \`nonGrantable: true\``);
+	if (base === "validate" && declaration.nonGrantable !== true) throw new Error(`${label}: a "validate" operation reports what a policy card compiles to, which only a caller the realm's own permissions let read the card may learn, so no policy may grant it; declare it with \`nonGrantable: true\``);
+	if (base === "validate") {
+		for (let key of ["params", "input"]) if (declaration[key] !== void 0) throw new Error(`${label}: a "validate" operation takes no payload, since the card it is invoked on is the whole question, so it carries no \`${key}\``);
+	}
+	let clauseKeys = CLAUSE_KEYS[base];
+	let legalKeys = new Set([
+		...COMMON_DECLARATION_KEYS,
+		...clauseKeys,
+		...MODIFIER_KEYS[base] ?? []
+	]);
+	for (let declaredKey of Object.keys(declaration)) if (!legalKeys.has(declaredKey)) throw new Error(`${label}: "${declaredKey}" is not a valid key for a "${base}" operation; valid keys are ${quoteList([...legalKeys].sort())}`);
+	let paramNames = assertValidParamsSchema(label, declaration.params);
+	if (declaration.optimistic !== void 0 && typeof declaration.optimistic !== "boolean") throw new Error(`${label}: \`optimistic\` must be a boolean`);
+	if (declaration.nonGrantable !== void 0 && typeof declaration.nonGrantable !== "boolean") throw new Error(`${label}: \`nonGrantable\` must be a boolean`);
+	if (declaration.label !== void 0) {
+		let problem = operationLabelProblem(declaration.label);
+		if (problem) throw new Error(`${label}: ${problem}`);
+	}
+	if (declaration.links !== void 0) {
+		let strategies = base === "query" ? LINK_STRATEGIES : READ_LINK_STRATEGIES;
+		if (!strategies.includes(declaration.links)) throw new Error(`${label}: \`links\` must name how much of the card's link graph ${base === "query" ? "each of this query's results carries" : "this read carries"} — one of ${quoteList(strategies)}${base === "read" && declaration.links === "none" ? `. A read's strategy governs the card's plain GET, which the host loads the card with to render and edit it, so under "none" an edit to a link field would replace the stored links the editor was never shown; "ids" narrows a read without hiding them` : ""}`);
+	}
+	if (declaration.html !== void 0) assertValidHtmlDeclaration(label, base, declaration.html);
+	if (declaration.input !== void 0) assertBxlProgram(label, "input", declaration.input);
+	if (base === "explain" && declaration.input !== void 0) throw new Error(`${label}: an "explain" operation answers the question its payload asks, so it carries no \`input\` to rewrite it`);
+	let usedClauses = clauseKeys.filter((clause) => declaration[clause] !== void 0 && !TYPE_NAMING_KEYS.includes(clause));
+	let hasProgram = declaration.transformations !== void 0;
+	if (hasProgram) {
+		assertBxlProgram(label, "transformations", declaration.transformations);
+		let noProgram = noProgramReason(owner, base);
+		if (noProgram) throw new Error(`${label}: ${noProgram}, so it carries no \`transformations\``);
+		if (usedClauses.length > 0) throw new Error(`${label}: a declaration expresses its work either with clauses (${quoteList(usedClauses)}) or with a raw \`transformations\` program, not both`);
+	}
+	let required = REQUIRED_CLAUSE[base];
+	if (required !== void 0 && declaration[required] === void 0) {
+		if (TYPE_NAMING_KEYS.includes(required)) throw new Error(`${label}: a "${base}" operation needs \`${required}\` to name what it creates`);
+		if (!hasProgram) throw new Error(`${label}: a "${base}" operation needs \`${required}\`, or a raw \`transformations\` program`);
+	}
+	assertValidClauses(label, base, declaration, key);
+	if (declaration.output !== void 0 && !isPlainObject(declaration.output)) throw new Error(`${label}: \`output\` must be a projection object or a bxl program`);
+	if (base === "explain" && declaration.output !== void 0) throw new Error(`${label}: an "explain" operation answers with the policy's explanation as the gate reports it, so it carries no \`output\` to reshape it`);
+	if (base === "validate" && declaration.output !== void 0) throw new Error(`${label}: a "validate" operation answers with what the policy card compiles to, as compiling reports it, so it carries no \`output\` to reshape it`);
+	assertReferencesResolve(label, declaration, paramNames);
+	if (base === "query") assertQueryIsWellFormed(label, declaration.query);
+}
+function assertQueryIsWellFormed(label, query) {
+	if (!isPlainObject(query) || holdsReference(query)) return;
+	try {
+		assertQuery(withTypeSentinels(query));
+	} catch (error) {
+		if (error instanceof InvalidQueryError) throw new Error(`${label}: \`query\` is not a query the realm accepts — ${error.message}`);
+		throw error;
+	}
+}
+function holdsReference(node) {
+	if (Array.isArray(node)) return node.some(holdsReference);
+	if (!isPlainObject(node)) return false;
+	if (hasOwn(node, "$ref") || hasOwn(node, "$bxl")) return true;
+	return Object.values(node).some(holdsReference);
+}
+function withTypeSentinels(node) {
+	if (typeof node === "function") return {
+		notJson: () => {},
+		module: TYPE_SLOT_SENTINEL,
+		name: TYPE_SLOT_SENTINEL
+	};
+	if (Array.isArray(node)) return node.map(withTypeSentinels);
+	if (!isPlainObject(node)) return node;
+	return Object.fromEntries(Object.entries(node).map(([key, value]) => [key, withTypeSentinels(value)]));
+}
+var TYPE_SLOT_SENTINEL = "$operation-type-slot";
+function assertValidClauses(label, base, declaration, name) {
+	if (declaration.append !== void 0) {
+		let append = declaration.append;
+		if (!isPlainObject(append)) throw new Error(`${label}: \`append\` must be an object naming the field to append \`to\` and the \`value\` to append`);
+		assertOnlyKeys(label, "append", append, ["to", "value"]);
+		if (typeof append.to !== "string" || append.to.length === 0) throw new Error(`${label}: \`append.to\` must name the collection field to append to`);
+		if (append.value === void 0) throw new Error(`${label}: \`append\` must carry a \`value\` to append`);
+	}
+	if (declaration.assert !== void 0) {
+		let assertion = declaration.assert;
+		if (!isPlainObject(assertion)) throw new Error(`${label}: \`assert\` must be an object naming the collection that must stay \`unique\` and the value to key it \`by\``);
+		assertOnlyKeys(label, "assert", assertion, [
+			"unique",
+			"by",
+			"message",
+			"snapshot"
+		]);
+		if (typeof assertion.unique !== "string" || assertion.unique.length === 0) throw new Error(`${label}: \`assert.unique\` must name the collection field that must not already hold the value`);
+		if (assertion.by === void 0) throw new Error(`${label}: \`assert\` must carry a \`by\` value to key the uniqueness check on`);
+		if (assertion.message !== void 0 && typeof assertion.message !== "string") throw new Error(`${label}: \`assert.message\` must be a string`);
+		if (assertion.snapshot !== void 0 && typeof assertion.snapshot !== "boolean") throw new Error(`${label}: \`assert.snapshot\` must be a boolean`);
+	}
+	for (let clause of ["set", "fill"]) {
+		let value = declaration[clause];
+		if (value === void 0) continue;
+		if (!isPlainObject(value) || Object.keys(value).length === 0) throw new Error(`${label}: \`${clause}\` must be an object mapping field names to values`);
+	}
+	if (declaration.of !== void 0) {
+		if (typeof declaration.of !== "function") throw new Error(`${label}: \`of\` must be the card class to create, or a thunk returning it`);
+		if (isDefConstructor(declaration.of) && !isSubclassOf(declaration.of, CardDef)) throw new Error(`${label}: \`of\` must be a card class — only a card can be created`);
+	}
+	if (base === "callApi") assertDeclaresARequest(label, declaration);
+	if (base === "appendLine") assertAppendsALine(label, declaration);
+	if (base === "appendContainsMany" && !isBuiltInAppend(name, declaration)) assertNamesItemsToAppend(label, declaration);
+	if (base === "query" && declaration.query !== void 0) {
+		let query = declaration.query;
+		if (!isPlainObject(query) || Object.keys(query).length === 0) throw new Error(`${label}: \`query\` must be an object with at least one of \`filter\`, \`sort\`, \`queryString\`, \`page\` and \`realms\``);
+		assertOnlyKeys(label, "query", query, [
+			"filter",
+			"sort",
+			"queryString",
+			"page",
+			"realms"
+		]);
+		if (query.queryString !== void 0) {
+			let term = query.queryString;
+			if (!(typeof term === "string" && term.length > 0) && !isReferenceMarker(term)) throw new Error(`${label}: \`query.queryString\` must be a search term, or a reference to one`);
+		}
+		if (query.page !== void 0) {
+			if (!isPlainObject(query.page)) throw new Error(`${label}: \`query.page\` must be an object with \`size\` and an optional \`number\``);
+			assertOnlyKeys(label, "query.page", query.page, ["size", "number"]);
+			let size = query.page.size;
+			if (typeof size !== "number" || !Number.isInteger(size) || size < 1) throw new Error(`${label}: \`query.page.size\` must be a positive integer`);
+			let pageNumber = query.page.number;
+			if (pageNumber !== void 0 && (typeof pageNumber !== "number" || !Number.isInteger(pageNumber) || pageNumber < 0)) throw new Error(`${label}: \`query.page.number\` must be a whole number, counting from 0`);
+		}
+		if (query.realms !== void 0) {
+			let realms = query.realms;
+			if (!Array.isArray(realms) || realms.length === 0 || realms.some((realm) => typeof realm !== "string" || realm.length === 0)) throw new Error(`${label}: \`query.realms\` must be a non-empty array of realm URLs`);
+		}
+	}
+}
+function assertDeclaresARequest(label, declaration) {
+	let { method, url, json, graphql } = declaration;
+	if (typeof url !== "string" || url.length === 0) throw new Error(`${label}: \`url\` must be the absolute URL the request is sent to, with each path segment the payload fills written \`{name}\``);
+	if (method !== void 0 && !CALL_API_METHODS.includes(method)) throw new Error(`${label}: \`method\` must be one of ${quoteList(CALL_API_METHODS)}`);
+	for (let part of [
+		"path",
+		"headers",
+		"query"
+	]) {
+		let value = declaration[part];
+		if (value !== void 0 && !isPlainObject(value)) throw new Error(`${label}: \`${part}\` must be an object mapping each name to its value`);
+	}
+	if (json !== void 0 && graphql !== void 0) throw new Error(`${label}: a request carries one body — \`json\` or \`graphql\`, not both`);
+	if (graphql !== void 0) {
+		if (!isPlainObject(graphql)) throw new Error(`${label}: \`graphql\` must be an object with the \`document\` to send and its \`variables\``);
+		assertOnlyKeys(label, "graphql", graphql, ["document", "variables"]);
+		if (graphql.variables !== void 0 && !isPlainObject(graphql.variables)) throw new Error(`${label}: \`graphql.variables\` must be an object mapping each variable to its value`);
+	}
+	if (method === "GET" && (json !== void 0 || graphql !== void 0)) throw new Error(`${label}: a GET request carries no body, so it takes no \`${json !== void 0 ? "json" : "graphql"}\``);
+}
+function assertAppendsALine(label, declaration) {
+	if (declaration.input !== void 0) return;
+	let line = declaration.params?.line;
+	if (line === void 0) throw new Error(`${label}: an "appendLine" operation appends the line its payload carries, so it declares a \`line\` param — or an \`input\` program that produces one`);
+	if (isPlainObject(line)) throw new Error(`${label}: \`params.line\` is the text a line holds, so it is a field class rather than a linkTo(…)`);
+}
+function isBuiltInAppend(name, declaration) {
+	return name === "appendContainsMany" && declaration.field === void 0 && declaration.item === void 0 && declaration.fields === void 0;
+}
+function assertNamesItemsToAppend(label, declaration) {
+	let singular = declaration.field !== void 0 || declaration.item !== void 0;
+	let plural = declaration.fields !== void 0;
+	if (singular && plural) throw new Error(`${label}: an "appendContainsMany" operation names one field with its \`item\`, or several under \`fields\` — not both`);
+	if (!singular && !plural) throw new Error(`${label}: an "appendContainsMany" operation needs \`field\` and \`item\`, or \`fields\` mapping each field to the item to append to it`);
+	if (plural) {
+		let fields = declaration.fields;
+		if (!isPlainObject(fields) || Object.keys(fields).length === 0) throw new Error(`${label}: \`fields\` must be an object mapping each \`containsMany\` field to the item to append to it`);
+		for (let [name, item] of Object.entries(fields)) if (item === void 0) throw new Error(`${label}: \`fields.${name}\` must carry the item to append to "${name}"`);
+		return;
+	}
+	if (typeof declaration.field !== "string" || declaration.field.length === 0) throw new Error(`${label}: \`field\` must name the \`containsMany\` field to append to`);
+	if (declaration.item === void 0) throw new Error(`${label}: an "appendContainsMany" operation needs an \`item\` to append to "${declaration.field}"`);
+}
+function assertValidParamsSchema(label, schema) {
+	if (schema === void 0) return /* @__PURE__ */ new Set();
+	if (!isPlainObject(schema)) throw new Error(`${label}: \`params\` must be an object mapping param names to a field class or linkTo(…)`);
+	let names = /* @__PURE__ */ new Set();
+	for (let [name, type] of Object.entries(schema)) {
+		if (isPlainObject(type)) {
+			if (typeof type.$linkTo !== "function") throw new Error(`${label}: param "${name}" must be a field class or linkTo(…)`);
+			assertOnlyKeys(label, `params.${name}`, type, ["$linkTo"]);
+			let linked = type.$linkTo;
+			if (isDefConstructor(linked) && !isSubclassOf(linked, CardDef) && !isSubclassOf(linked, FileDef)) throw new Error(`${label}: param "${name}" links to a card or file class — a link points at something with a URL`);
+		} else if (!isFieldDefConstructor(type)) throw new Error(`${label}: param "${name}" must be a field class or linkTo(…)${isDefConstructor(type) ? ", and a card or file identity is a linkTo(…) param" : ""}`);
+		names.add(name);
+	}
+	return names;
+}
+function isFieldDefConstructor(value) {
+	return typeof value === "function" && isSubclassOf(value, FieldDef);
+}
+function assertReferencesResolve(label, declaration, paramNames) {
+	let ancestors = /* @__PURE__ */ new Set();
+	let walk = (node, path, position) => {
+		if (node === null) return;
+		if (typeof node === "function") {
+			if (position !== "type") throw new Error(`${label}: \`${path}\` is a function; a declaration is data — name a run-time value with params(), actor(), instance(), realmConfig() or card(), or a program with the bxl tag`);
+			if (isDefConstructor(node) && !isSubclassOf(node, CardDef) && !isSubclassOf(node, FileDef)) throw new Error(`${label}: \`${path}\` must be a card or file class — a field has no type of its own to name`);
+			return;
+		}
+		if (typeof node !== "object") {
+			if (typeof node === "symbol" || typeof node === "bigint") throw new Error(`${label}: \`${path}\` is ${describeValue(node)}, which a declaration cannot carry`);
+			if (node === void 0) throw new Error(`${label}: \`${path}\` is undefined; omit an optional key rather than declaring it as undefined`);
+			if (typeof node === "number" && !Number.isFinite(node)) throw new Error(`${label}: \`${path}\` is ${node}, which serializes as null`);
+			return;
+		}
+		if (ancestors.has(node)) throw new Error(`${label}: \`${path}\` refers back to a value that contains it; a declaration is a tree`);
+		if (isBxlMarker(node)) {
+			assertBxlProgram(label, path, node);
+			return;
+		}
+		if (isReferenceMarker(node)) {
+			assertValidReference(label, path, node, paramNames, ancestors);
+			return;
+		}
+		if (!Array.isArray(node) && !isPlainObject(node)) throw new Error(`${label}: \`${path}\` is ${describeValue(node)}; a declaration carries plain objects, arrays and primitives`);
+		ancestors.add(node);
+		if (Array.isArray(node)) {
+			let elementPosition = positionInside(position);
+			node.forEach((entry, index) => walk(entry, `${path}[${index}]`, elementPosition));
+		} else for (let [key, value] of Object.entries(node)) {
+			if (position === "declaration" && key === "params") continue;
+			walk(value, path === "" ? key : `${path}.${key}`, position === "declaration" && key === "query" && declaration.base !== "query" ? "value" : positionUnder(position, key));
+		}
+		ancestors.delete(node);
+	};
+	walk(declaration, "", "declaration");
+}
+function positionUnder(position, key) {
+	switch (position) {
+		case "declaration":
+			if (key === "of") return "type";
+			return key === "query" ? "query" : "value";
+		case "query":
+			if (key === "filter") return "filter";
+			return key === "sort" ? "sortList" : "value";
+		case "filter":
+			if (key === "on" || key === "type") return "type";
+			if (key === "any" || key === "every") return "filterList";
+			return key === "not" ? "filter" : "value";
+		case "sortEntry": return key === "on" ? "type" : "value";
+		case "type":
+		case "value":
+		case "filterList":
+		case "sortList": return "value";
+	}
+}
+function positionInside(position) {
+	switch (position) {
+		case "filterList": return "filter";
+		case "sortList": return "sortEntry";
+		default: return "value";
+	}
+}
+function describeValue(value) {
+	if (value === void 0) return "undefined";
+	if (typeof value === "symbol") return "a symbol";
+	if (typeof value === "bigint") return "a bigint";
+	if (typeof value === "function") return "a function";
+	let name = value?.constructor?.name;
+	return name ? `a ${name} instance` : "a non-plain object";
+}
+function assertValidReference(label, path, node, paramNames, ancestors) {
+	if (ancestors.has(node)) throw new Error(`${label}: \`${path}\` refers back to a value that contains it; a declaration is a tree`);
+	let reference = node;
+	switch (reference.$ref) {
+		case "params": {
+			assertOnlyKeys(label, path, reference, ["$ref", "key"]);
+			let key = reference.key;
+			if (typeof key !== "string" || key.length === 0) throw new Error(`${label}: the params reference at \`${path}\` must name a param`);
+			if (!paramNames.has(key)) throw new Error(`${label}: \`${path}\` references the param "${key}", which the \`params\` schema does not declare`);
+			return;
+		}
+		case "actor":
+			if (reference.key !== void 0) throw new Error(`${label}: the actor reference at \`${path}\` carries a key; actor() is the caller's user id and has no members to read`);
+			assertOnlyKeys(label, path, reference, ["$ref"]);
+			return;
+		case "instance":
+			assertOnlyKeys(label, path, reference, ["$ref", "key"]);
+			if (reference.key !== void 0 && (typeof reference.key !== "string" || reference.key.length === 0)) throw new Error(`${label}: the instance reference at \`${path}\` must name a member, or none at all`);
+			return;
+		case "realmConfig":
+			assertOnlyKeys(label, path, reference, ["$ref", "key"]);
+			if (reference.key !== void 0 && (typeof reference.key !== "string" || reference.key.length === 0)) throw new Error(`${label}: the realmConfig reference at \`${path}\` must name a setting, or none at all`);
+			return;
+		case "card": {
+			assertOnlyKeys(label, path, reference, ["$ref", "value"]);
+			let value = reference.value;
+			if (typeof value === "string") {
+				if (value.length === 0) throw new Error(`${label}: the card reference at \`${path}\` must carry a card URL or a reference to one`);
+				return;
+			}
+			if (!isReferenceMarker(value)) throw new Error(`${label}: the card reference at \`${path}\` must carry a card URL or a reference to one`);
+			if (value.$ref === "actor") throw new Error(`${label}: ${actorIsNotACard(`the card reference at \`${path}\``)}`);
+			ancestors.add(node);
+			assertValidReference(label, `${path}.value`, value, paramNames, ancestors);
+			ancestors.delete(node);
+			return;
+		}
+		default: throw new Error(`${label}: \`${path}\` is not a typed reference; build one with params(), actor(), instance(), realmConfig() or card()`);
+	}
+}
+function assertBxlProgram(label, path, value) {
+	if (!isBxlMarker(value) || typeof value.$bxl !== "string" || value.$bxl.length === 0) throw new Error(`${label}: \`${path}\` must be a program written with the bxl tag`);
+	assertOnlyKeys(label, path, value, ["$bxl"]);
+}
+function assertOnlyKeys(label, path, node, allowed) {
+	for (let key of Object.keys(node)) if (!allowed.includes(key)) throw new Error(`${label}: "${key}" is not a valid key for \`${path}\`; valid keys are ${quoteList(allowed)}`);
+}
+function assertOptionalReferenceKey(kind, key) {
+	if (key === void 0) return;
+	if (typeof key !== "string" || key.length === 0) throw new Error(`${kind}() takes the name of a member to read, or no argument at all`);
+}
+function isReferenceMarker(value) {
+	return isPlainObject(value) && hasOwn(value, "$ref");
+}
+function isBxlMarker(value) {
+	return isPlainObject(value) && hasOwn(value, "$bxl");
+}
+function isPlainObject(value) {
+	if (value == null || typeof value !== "object" || Array.isArray(value)) return false;
+	let proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+function isBaseOperationName(value) {
+	return typeof value === "string" && BASE_OPERATIONS.includes(value);
+}
+function declarationLabel(owner, key) {
+	return `@operation "${key}" on ${owner.name || owner.displayName || "card"}`;
+}
+function quoteList(values) {
+	return values.map((value) => `"${value}"`).join(", ");
+}
+function operations(target, opts) {
+	return buildOperations(subjectFor(target), {
+		transport: getOperationsTransport(),
+		...opts ? { options: opts } : {},
+		subject: (other) => subjectFor(other),
+		codeRef: (value) => identifyDef(value),
+		resourceFor: (instance) => adoptedResource(instance)
+	});
+}
+function adoptedResource(instance) {
+	let { id: _id, ...resource } = serializeCard(instance, {
+		useAbsoluteURL: true,
+		omitQueryFields: true,
+		includedScope: "none"
+	}).data;
+	return resource;
+}
+function subjectFor(target) {
+	if (typeof target === "string") return {
+		scope: "instance",
+		family: "file",
+		displayName: `file ${target}`,
+		operations: carriedOperations(FileDef),
+		id: target
+	};
+	if (isDefConstructor(target)) {
+		let codeRef = identifyCard(target);
+		if (!codeRef) throw new Error(`operations() takes a class some module exports, and no module exports ${defName(target)} — an operation on a type names it by its module and export`);
+		return {
+			scope: "type",
+			family: familyOf(target, "operations"),
+			displayName: defName(target),
+			operations: carriedOperations(target),
+			codeRef
+		};
+	}
+	let owner = defConstructorFor(target, "operations");
+	let instance = target;
+	let realm = instance[realmURL];
+	let codeRef = identifyCard(owner);
+	return {
+		scope: "instance",
+		family: familyOf(owner, "operations"),
+		displayName: defName(owner),
+		operations: carriedOperations(owner),
+		...instance.id ? { id: instance.id } : {},
+		...instance[localId] ? { localId: instance[localId] } : {},
+		...realm ? { realmURL: realm.href } : {},
+		...codeRef ? { codeRef } : {}
+	};
+}
+function carriedOperations(owner) {
+	let carried = Object.create(null);
+	for (let base of impliedOperations(owner)) carried[base] = {
+		base,
+		declared: false
+	};
+	for (let [name, declaration] of Object.entries(declaredOperations(owner))) carried[name] = {
+		base: declaration.base,
+		declared: true,
+		...declaration.optimistic === void 0 ? {} : { optimistic: declaration.optimistic },
+		...declaration.base === "query" ? { query: queryDeclaration(declaration) } : {}
+	};
+	return carried;
+}
+function queryDeclaration(declaration) {
+	let { query, params } = declaration;
+	return {
+		...query === void 0 ? {} : { query },
+		...params === void 0 ? {} : { params }
+	};
+}
+function familyOf(owner, reader) {
+	if (isSubclassOf(owner, FieldDef)) throw new Error(`${reader}() takes a card, a file or a class of one; a field has no URL of its own, so nothing is invocable on it — reach a field's data through the operations of the card that contains it`);
+	if (isSubclassOf(owner, CardDef)) return "card";
+	if (isSubclassOf(owner, FileDef)) return "file";
+	return "base";
+}
+function identifyDef(value) {
+	return codeRefForDef(value, identifyCard);
+}
+function defName(owner) {
+	return owner.displayName || owner.name || "card";
+}
+(globalThis.__boxelBundledBaseScopedCSS ??= {})["operations"] = {
+	"css": [],
+	"imports": ["card-api"]
+};
+(globalThis.__boxelBundledBaseIdentities ??= {})["operations"] = {
+	"BASE_OPERATIONS": BASE_OPERATIONS,
+	"CALL_API_METHODS": CALL_API_METHODS,
+	"actor": actor,
+	"bxl": bxl,
+	"card": card,
+	"getDeclaredOperations": getDeclaredOperations,
+	"getOperations": getOperations,
+	"instance": instance,
+	"linkTo": linkTo,
+	"operation": operation,
+	"operations": operations,
+	"params": params,
+	"realmConfig": realmConfig
+};
+//#endregion
+export { card as a, instance as c, operations as d, params as f, bxl as i, linkTo as l, CALL_API_METHODS as n, getDeclaredOperations as o, realmConfig as p, actor as r, getOperations as s, BASE_OPERATIONS as t, operation as u };