@formancy/server-core 0.4.0 → 0.5.0

package/dist/index.mjs

@@ -2,10 +2,11 @@ import { CHALLENGE_TTL_SECONDS, DEFAULT_MAX_NUMBER, decodeSolution, encodeSoluti
 import { hmac } from "@noble/hashes/hmac.js";
 import { sha256 } from "@noble/hashes/sha2.js";
 import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils.js";
+import { createFormEngine, expressionProblems, runScenarios, unknownReferences } from "@formancy/core";
 import { diffSchemas, modelDataPaths, schemaHash } from "@formancy/spec";
-import { createFormEngine, expressionProblems, unknownReferences } from "@formancy/core";
 import { check } from "recheck";
 import { validateSchema } from "@formancy/spec/validate";
+import { comparedToLastRun, isModelRequestKind, modelBriefing, readScenario } from "@formancy/builder-core";
 //#region src/options-membership.ts
 /**
 * Every sourced answer in a submission, as `path → { source, value }`.
@@ -137,6 +138,7 @@ const AUDIT_ACTIONS = [
 	"auth.login.failed",
 	"form.published",
 	"form.access.changed",
+	"form.examples.changed",
 	"submission.created",
 	"submission.read",
 	"submission.exported",
@@ -144,7 +146,8 @@ const AUDIT_ACTIONS = [
 	"user.created",
 	"apiKey.created",
 	"apiKey.revoked",
-	"delivery.replayed"
+	"delivery.replayed",
+	"model.asked"
 ];
 /**
 * An entry from an actor, with the fields spread the way the record stores
@@ -486,7 +489,8 @@ async function offerUpload(deps, input) {
 		storageKey: `${input.form.id}/${id}`,
 		state: "offered",
 		createdAt: deps.now().toISOString(),
-		submissionId: null
+		submissionId: null,
+		receivingUntil: null
 	};
 	await deps.storage.insertFile(file);
 	return {
@@ -658,6 +662,70 @@ function fileFieldPaths(schema) {
 	return modelDataPaths(schema.model).filter((path) => fileFieldAt(schema, path)?.type === "file");
 }
 //#endregion
+//#region src/signing.ts
+/**
+* The keys the public plane hands out: a draft's and a response's, each an HMAC under the
+* deployment's signing key over what it opens.
+*
+* Stateless, the shape the proof-of-work challenge uses
+* ([0059](../../../docs/decisions/0059-proof-of-work-not-a-captcha.md)): handing one out is
+* public and unauthenticated, so it must not be a write — a key kept in a table is a table an
+* attacker fills by asking for keys they never use. Both in one file, so what each is signed
+* over can be read side by side, and nobody has to check two files to see that one cannot
+* stand in for the other.
+*/
+function signed(secret, message) {
+	return bytesToHex(hmac(sha256, utf8ToBytes(secret), utf8ToBytes(message)));
+}
+/**
+* The key to a draft: HMAC over the form and the draft id
+* ([0062](../../../docs/decisions/0062-a-draft-carries-its-own-key.md)).
+*
+* Bound to the FORM as well as the id so a key cannot be carried to a draft of another form
+* that happens to share an id. The message is unchanged since 0.2.0, which is what keeps every
+* key handed out since then opening its draft.
+*/
+function draftKey(secret, formId, draftId) {
+	return signed(secret, `${formId}:${draftId}`);
+}
+/**
+* The token a response is sent with: the id it will be stored under, and an HMAC over the form
+* and that id ([0169](../../../docs/decisions/0169-a-response-is-stored-once.md)).
+*
+* The id travels in the clear because the server has to read it back, and the signature is
+* what makes it the server's choice rather than the sender's. The message begins with a word a
+* form id never is, so a draft's key — signed over `form:draft` — is never also a valid
+* signature for a response with the same id, and the reverse.
+*/
+function submissionToken(secret, formId, id) {
+	return `${id}.${signed(secret, `submission:${formId}:${id}`)}`;
+}
+/**
+* The id a token names, when this server signed it for this form; otherwise undefined.
+*
+* Read from the LAST dot, since the signature is hex and the id is whatever `newId` minted. A
+* forged token, another form's, one signed under a key this server no longer has, and one that
+* is not a token at all are the same answer: no id.
+*/
+function submissionTokenId(secret, formId, token) {
+	const dot = token.lastIndexOf(".");
+	if (dot <= 0) return void 0;
+	const id = token.slice(0, dot);
+	return sameToken(token, submissionToken(secret, formId, id)) ? id : void 0;
+}
+/**
+* Compared in constant time.
+*
+* A byte-at-a-time comparison that returns early leaks how much of a guess was
+* right, and a token is guessed one byte at a time by exactly that signal.
+*/
+function sameToken(a, b) {
+	if (a.length !== b.length) return false;
+	let differences = 0;
+	for (let at = 0; at < a.length; at += 1) differences |= a.charCodeAt(at) ^ b.charCodeAt(at);
+	return differences === 0;
+}
+//#endregion
 //#region src/use-cases.ts
 async function resolveForm(deps, path) {
 	const form = await deps.storage.getFormByPath(path);
@@ -673,15 +741,6 @@ async function resolveForm(deps, path) {
 	};
 }
 /**
-* Accept one submission: resolve the version the client says it rendered,
-* replay the engine over the submitted data, and store the CANONICAL result.
-*
-* The replay is the whole point. Computed values are recomputed and overwrite
-* whatever arrived; visibility is evaluated server-side and hidden branches
-* are stripped, so a client cannot smuggle data by lying about what was shown.
-* Client validation is UX; this is truth.
-*/
-/**
 * Change who may submit a form, and from where.
 *
 * Separate from publishing on purpose: access is a property of the deployment,
@@ -697,102 +756,6 @@ async function setFormAccess(deps, input) {
 	});
 	return { ok: true };
 }
-async function createSubmission(deps, input) {
-	const form = await deps.storage.getFormByPath(input.path);
-	if (form === void 0) return {
-		ok: false,
-		kind: "unknown_form"
-	};
-	if (!maySubmit(form, input.actor ?? "anonymous", input.origin)) return {
-		ok: false,
-		kind: "forbidden"
-	};
-	const current = await resolveForm(deps, input.path);
-	if (current === void 0) return {
-		ok: false,
-		kind: "unknown_form"
-	};
-	if (input.declaredSchemaHash !== current.schemaHash) return {
-		ok: false,
-		kind: "version_changed",
-		current
-	};
-	const engine = createFormEngine({
-		schema: current.schema,
-		initialValue: input.data,
-		capabilities: deps.capabilities,
-		mode: "server",
-		...deps.checks === void 0 ? {} : { checks: deps.checks }
-	});
-	await engine.settle();
-	const outcome = engine.submit();
-	if (!outcome.ok) return {
-		ok: false,
-		kind: "invalid",
-		errors: outcome.errors
-	};
-	const membership = await checkMembership(current.schema, engine.value(), deps.optionsSources);
-	if (!membership.ok) return membership.kind === "invalid" ? {
-		ok: false,
-		kind: "invalid",
-		errors: membership.errors
-	} : {
-		ok: false,
-		kind: "source_unavailable",
-		source: membership.source
-	};
-	const id = deps.newId();
-	const hooks = await deps.storage.webhooksForForm(current.formId);
-	const body = JSON.stringify({
-		id,
-		form: input.path,
-		data: engine.value()
-	});
-	const queued = hooks.map((hook) => ({
-		id: deps.newId(),
-		webhookId: hook.id,
-		submissionId: id,
-		eventId: deps.newId(),
-		body,
-		attempt: 0,
-		nextAttemptAt: deps.nowIso(),
-		state: "pending",
-		lastError: null
-	}));
-	const claimable = await filesToClaim(deps.storage, {
-		schema: current.schema,
-		formId: current.formId,
-		data: engine.value()
-	});
-	if (!claimable.ok) return {
-		ok: false,
-		kind: "invalid",
-		errors: { _files: [`unknown_file:${claimable.unknown.join(",")}`] }
-	};
-	const at = deps.nowIso();
-	await deps.storage.insertSubmission({
-		id,
-		formId: current.formId,
-		formVersionId: current.versionId,
-		data: engine.value(),
-		submittedAt: at
-	}, queued, claimable.ids, {
-		id: deps.newId(),
-		at,
-		action: "submission.created",
-		subject: input.path,
-		detail: {
-			submissionId: id,
-			version: current.version,
-			authenticated: input.actor === "authenticated"
-		}
-	});
-	return {
-		ok: true,
-		id,
-		canonicalData: engine.value()
-	};
-}
 /** The submissions of one form, newest first, each tagged with the schema
 *  version that produced it. Undefined for an unknown form: the caller must
 *  404, and an empty list would lie about that. */
@@ -873,39 +836,17 @@ function cellValue(data, column) {
 function csvCell(value) {
 	return /[",\n\r]/.test(value) ? `"${value.replaceAll("\"", "\"\"")}"` : value;
 }
-/** Save (or re-save) a partial form, bound to the CURRENT version. Undefined
-*  for an unknown form. */
-/**
-* The token that proves the bearer started this draft.
-*
-* HMAC over the form and the draft id, the same stateless shape the
-* proof-of-work challenge uses
-* ([0059](../../../docs/decisions/0059-proof-of-work-not-a-captcha.md)): no
-* second table, and no lookup before the check. Bound to the FORM as well as the
-* id so a token cannot be carried to a draft of another form that happens to
-* share an id.
-*/
-function draftToken(secret, formId, draftId) {
-	return bytesToHex(hmac(sha256, utf8ToBytes(secret), utf8ToBytes(`${formId}:${draftId}`)));
-}
-/**
-* Compared in constant time.
-*
-* A byte-at-a-time comparison that returns early leaks how much of a guess was
-* right, and a token is guessed one byte at a time by exactly that signal.
-*/
-function sameToken(a, b) {
-	if (a.length !== b.length) return false;
-	let differences = 0;
-	for (let at = 0; at < a.length; at += 1) differences |= a.charCodeAt(at) ^ b.charCodeAt(at);
-	return differences === 0;
-}
 /**
 * Start a draft: the server picks the id, and signs it.
 *
 * The id is the server's because an id a caller supplies is an id a caller can
 * enumerate — and enumerating them was enough to read other people's
 * part-filled answers.
+*
+* A draft is one response, so it comes with the token that response is sent with, naming the
+* draft's own id ([0169](../../../docs/decisions/0169-a-response-is-stored-once.md)). Resuming
+* hands back the same one, so a response whose answer was lost and is sent again after a reload
+* is refused as already sent rather than stored twice.
 */
 async function startDraft(deps, input) {
 	const current = await resolveForm(deps, input.path);
@@ -913,13 +854,16 @@ async function startDraft(deps, input) {
 	const draftId = deps.newId();
 	return {
 		draftId,
-		token: draftToken(deps.draftSecret, current.formId, draftId)
+		token: draftKey(deps.draftSecret, current.formId, draftId),
+		submissionToken: submissionToken(deps.draftSecret, current.formId, draftId)
 	};
 }
+/** Save (or re-save) a partial form, bound to the CURRENT version. Undefined
+*  for an unknown form. */
 async function saveDraft(deps, input) {
 	const current = await resolveForm(deps, input.path);
 	if (current === void 0) return void 0;
-	if (!sameToken(input.token, draftToken(deps.draftSecret, current.formId, input.draftId))) return {
+	if (!sameToken(input.token, draftKey(deps.draftSecret, current.formId, input.draftId))) return {
 		version: current.version,
 		saved: false
 	};
@@ -950,15 +894,17 @@ async function saveDraft(deps, input) {
 async function resumeDraft(deps, input) {
 	const current = await resolveForm(deps, input.path);
 	if (current === void 0) return void 0;
-	if (!sameToken(input.token, draftToken(deps.draftSecret, current.formId, input.draftId))) return;
+	if (!sameToken(input.token, draftKey(deps.draftSecret, current.formId, input.draftId))) return;
 	const draft = await deps.storage.getDraft(current.formId, input.draftId);
 	if (draft === void 0) return void 0;
+	const sendWith = submissionToken(deps.draftSecret, current.formId, draft.id);
 	if (draft.formVersionId === current.versionId) return {
 		outcome: "resumed",
 		version: current.version,
 		schema: current.schema,
 		schemaHash: current.schemaHash,
-		data: draft.data
+		data: draft.data,
+		submissionToken: sendWith
 	};
 	const draftVersion = await deps.storage.getVersionById(draft.formVersionId);
 	if (draftVersion === void 0) return void 0;
@@ -987,7 +933,8 @@ async function resumeDraft(deps, input) {
 		...severity === "lossy" ? { migration: {
 			severity,
 			changes
-		} } : {}
+		} } : {},
+		submissionToken: sendWith
 	};
 }
 const SEVERITY_RANK = {
@@ -1082,6 +1029,160 @@ async function listVersions(deps, path) {
 	}));
 }
 //#endregion
+//#region src/submitting.ts
+/**
+* The form a respondent fills in, with the token their response is sent with.
+*
+* A fresh id on every call, because every reading is a response that might be sent: two
+* people handed one token would find the second refused as already sent. Minting writes
+* nothing — an HMAC over the form and the id — so handing one to everybody who reads the form
+* costs this server a hash and fills no table
+* ([0169](../../../docs/decisions/0169-a-response-is-stored-once.md)).
+*/
+async function formToFill(deps, path) {
+	const resolved = await resolveForm(deps, path);
+	if (resolved === void 0) return void 0;
+	return {
+		...resolved,
+		submissionToken: submissionToken(deps.draftSecret, resolved.formId, deps.newId())
+	};
+}
+/**
+* Accept one submission: resolve the version the client says it rendered,
+* replay the engine over the submitted data, and store the CANONICAL result.
+*
+* The replay is the whole point. Computed values are recomputed and overwrite
+* whatever arrived; visibility is evaluated server-side and hidden branches
+* are stripped, so a client cannot smuggle data by lying about what was shown.
+* Client validation is UX; this is truth.
+*
+* And it is stored once. A response is stored under the id its token names, and the storage
+* refuses that id twice, so the same response sent again — a retry after an answer that never
+* arrived, a replay — is told it was sent rather than stored as somebody else
+* ([0169](../../../docs/decisions/0169-a-response-is-stored-once.md)).
+*/
+async function createSubmission(deps, input) {
+	const form = await deps.storage.getFormByPath(input.path);
+	if (form === void 0) return {
+		ok: false,
+		kind: "unknown_form"
+	};
+	const actor = input.actor ?? "anonymous";
+	if (!maySubmit(form, actor, input.origin)) return {
+		ok: false,
+		kind: "forbidden"
+	};
+	let id;
+	if (input.token === void 0) {
+		if (actor === "anonymous") return {
+			ok: false,
+			kind: "token_required"
+		};
+		id = deps.newId();
+	} else {
+		const named = submissionTokenId(deps.draftSecret, form.id, input.token);
+		if (named === void 0) return {
+			ok: false,
+			kind: "token_invalid"
+		};
+		if (await deps.storage.hasSubmission(named)) return {
+			ok: false,
+			kind: "token_spent",
+			id: named
+		};
+		id = named;
+	}
+	const current = await resolveForm(deps, input.path);
+	if (current === void 0) return {
+		ok: false,
+		kind: "unknown_form"
+	};
+	if (input.declaredSchemaHash !== current.schemaHash) return {
+		ok: false,
+		kind: "version_changed",
+		current
+	};
+	const engine = createFormEngine({
+		schema: current.schema,
+		initialValue: input.data,
+		capabilities: deps.capabilities,
+		mode: "server",
+		...deps.checks === void 0 ? {} : { checks: deps.checks }
+	});
+	await engine.settle();
+	const outcome = engine.submit();
+	if (!outcome.ok) return {
+		ok: false,
+		kind: "invalid",
+		errors: outcome.errors
+	};
+	const membership = await checkMembership(current.schema, engine.value(), deps.optionsSources);
+	if (!membership.ok) return membership.kind === "invalid" ? {
+		ok: false,
+		kind: "invalid",
+		errors: membership.errors
+	} : {
+		ok: false,
+		kind: "source_unavailable",
+		source: membership.source
+	};
+	const hooks = await deps.storage.webhooksForForm(current.formId);
+	const body = JSON.stringify({
+		id,
+		form: input.path,
+		data: engine.value()
+	});
+	const queued = hooks.map((hook) => ({
+		id: deps.newId(),
+		webhookId: hook.id,
+		submissionId: id,
+		eventId: deps.newId(),
+		body,
+		attempt: 0,
+		nextAttemptAt: deps.nowIso(),
+		state: "pending",
+		lastError: null
+	}));
+	const claimable = await filesToClaim(deps.storage, {
+		schema: current.schema,
+		formId: current.formId,
+		data: engine.value()
+	});
+	if (!claimable.ok) return {
+		ok: false,
+		kind: "invalid",
+		errors: { _files: [`unknown_file:${claimable.unknown.join(",")}`] }
+	};
+	const at = deps.nowIso();
+	if (!await deps.storage.insertSubmission({
+		id,
+		formId: current.formId,
+		formVersionId: current.versionId,
+		data: engine.value(),
+		submittedAt: at
+	}, queued, claimable.ids, {
+		id: deps.newId(),
+		at,
+		action: "submission.created",
+		subject: input.path,
+		...input.requestId === void 0 ? {} : { requestId: input.requestId },
+		detail: {
+			submissionId: id,
+			version: current.version,
+			authenticated: input.actor === "authenticated"
+		}
+	})) return {
+		ok: false,
+		kind: "token_spent",
+		id
+	};
+	return {
+		ok: true,
+		id,
+		canonicalData: engine.value()
+	};
+}
+//#endregion
 //#region src/redos.ts
 /** Every `pattern` in the model, with the data path of the field it sits on. */
 function patternsIn(fields, prefix) {
@@ -1138,6 +1239,7 @@ function createMemoryStorage() {
 	const users = /* @__PURE__ */ new Map();
 	const apiKeys = /* @__PURE__ */ new Map();
 	const files = /* @__PURE__ */ new Map();
+	const examples = /* @__PURE__ */ new Map();
 	return {
 		getFormByPath: async (path) => [...forms.values()].find((form) => form.path === path),
 		listForms: async () => [...forms.values()].map((form) => ({ ...form })),
@@ -1168,6 +1270,15 @@ function createMemoryStorage() {
 			if (audit !== void 0) audits.push({ ...audit });
 		},
 		getVersionById: async (id) => versions.get(id),
+		getExamples: async (formId) => {
+			const found = examples.get(formId);
+			return found === void 0 ? void 0 : { ...found };
+		},
+		keepExamples: async (record, audit) => {
+			if (!forms.has(record.formId)) throw new Error(`No form "${record.formId}"`);
+			examples.set(record.formId, { ...record });
+			if (audit !== void 0) audits.push({ ...audit });
+		},
 		findVersionByHash: async (formId, hash) => [...versions.values()].find((version) => version.formId === formId && version.schemaHash === hash),
 		latestVersionNumber: async (formId) => Math.max(0, ...[...versions.values()].filter((version) => version.formId === formId).map((version) => version.version)),
 		webhooksForForm: async (formId) => [...webhooks.values()].filter((hook) => hook.formId === formId).map((hook) => ({ ...hook })),
@@ -1194,14 +1305,41 @@ function createMemoryStorage() {
 			const found = files.get(id);
 			return found === void 0 ? void 0 : { ...found };
 		},
-		updateFile: async (record) => {
-			files.set(record.id, { ...record });
+		leaseFile: async (id, nowIso, untilIso) => {
+			const file = files.get(id);
+			if (file === void 0 || file.state !== "offered") return false;
+			if (file.receivingUntil !== null && file.receivingUntil > nowIso) return false;
+			files.set(id, {
+				...file,
+				receivingUntil: untilIso
+			});
+			return true;
+		},
+		settleFile: async (id, untilIso) => {
+			const file = files.get(id);
+			if (file === void 0 || file.state !== "offered" || file.receivingUntil !== untilIso) return false;
+			files.set(id, {
+				...file,
+				state: "stored",
+				receivingUntil: null
+			});
+			return true;
+		},
+		releaseFile: async (id, untilIso) => {
+			const file = files.get(id);
+			if (file === void 0 || file.receivingUntil !== untilIso) return false;
+			files.set(id, {
+				...file,
+				receivingUntil: null
+			});
+			return true;
 		},
 		abandonedFiles: async (beforeIso) => [...files.values()].filter((file) => file.state !== "claimed" && file.createdAt < beforeIso).map((file) => ({ ...file })),
 		deleteFiles: async (ids) => {
 			for (const id of ids) files.delete(id);
 		},
 		insertSubmission: async (record, queued, claimFileIds, audit) => {
+			if (submissions.some((stored) => stored.id === record.id)) return false;
 			submissions.push({ ...record });
 			for (const delivery of queued ?? []) deliveries.set(delivery.id, { ...delivery });
 			for (const id of claimFileIds ?? []) {
@@ -1213,7 +1351,9 @@ function createMemoryStorage() {
 				});
 			}
 			if (audit !== void 0) audits.push({ ...audit });
+			return true;
 		},
+		hasSubmission: async (id) => submissions.some((stored) => stored.id === id),
 		spendChallenge: async (challenge, expiresAtIso) => {
 			if (spentChallenges.has(challenge)) return false;
 			spentChallenges.set(challenge, expiresAtIso);
@@ -1439,6 +1579,184 @@ function isIpLiteral(host) {
 	return bare.includes(":");
 }
 //#endregion
+//#region src/examples.ts
+/** The examples kept for the form at `path`; none, for a form nobody wrote any for. */
+async function readExamples(deps, input) {
+	if (!can(input.actor, "form.publish")) return {
+		ok: false,
+		kind: "forbidden"
+	};
+	const form = await deps.storage.getFormByPath(input.path);
+	if (form === void 0) return {
+		ok: false,
+		kind: "unknown_form"
+	};
+	const kept = readKept(await deps.storage.getExamples(form.id));
+	return {
+		ok: true,
+		examples: {
+			...asExamples(kept.scenarios, kept.sample),
+			...kept.problems.length === 0 ? {} : { unreadable: kept.problems }
+		}
+	};
+}
+/**
+* Replace the examples of the form at `path`, and the sample they start from.
+*
+* Each is read as an example the way a builder reads a model's draft — `readScenario`, one
+* decision for both — and a list with any item that is not one keeps nothing. Paths are not
+* checked against the published form: an example is written for the form being edited, which
+* may name a field no version has yet, and the runner says so when it runs.
+*/
+async function keepExamples(deps, input) {
+	if (!can(input.actor, "form.publish")) return {
+		ok: false,
+		kind: "forbidden"
+	};
+	const form = await deps.storage.getFormByPath(input.path);
+	if (form === void 0) return {
+		ok: false,
+		kind: "unknown_form"
+	};
+	const read = readExamplesBody(input.examples);
+	if ("problems" in read) return {
+		ok: false,
+		kind: "invalid_examples",
+		problems: read.problems
+	};
+	await deps.storage.keepExamples({
+		formId: form.id,
+		scenarios: read.scenarios,
+		sample: read.sample,
+		updatedAt: deps.nowIso()
+	}, {
+		id: deps.newId(),
+		at: deps.nowIso(),
+		action: "form.examples.changed",
+		subject: input.path,
+		actorKind: input.actor.kind,
+		actorId: input.actor.id,
+		...input.requestId === void 0 ? {} : { requestId: input.requestId },
+		detail: {
+			examples: read.scenarios.length,
+			sample: read.sample !== null
+		}
+	});
+	return {
+		ok: true,
+		examples: asExamples(read.scenarios, read.sample)
+	};
+}
+/**
+* What publishing says about the form's examples: one sentence for each that held against the
+* version the form has and does not hold against the one being published.
+*
+* **Run as the server replays a submission**, in `server` mode, from the kept sample, and
+* compared by `comparedToLastRun` — the scenario panel's own verdict, so the publish cannot
+* call something a regression the panel would not
+* ([0091](../../../docs/decisions/0091-a-second-builder-is-a-binding.md)). An example that did
+* not hold before either is not this publish's doing, and one that holds again is good news;
+* neither is a warning.
+*
+* **It never refuses.** A publish may warn and never refuses over its examples
+* ([0097](../../../docs/decisions/0097-a-publish-may-warn.md)): a rule changed on purpose stops
+* its old example holding, and the person decides. A stored row that is not an example — one
+* edited around `keepExamples` — is read out before the run, as the admin reads it out, and
+* named; run as it was, the runner throws on it and every publish of the form is a 500.
+*/
+async function examplesThatStopHolding(storage, formId, before, after) {
+	if (before === void 0) return [];
+	const kept = readKept(await storage.getExamples(formId));
+	const leftOut = kept.problems.length === 0 ? [] : [`Not everything kept with this form's examples could be read, and what could not was not run: ${kept.problems.join(" ")}`];
+	if (kept.scenarios.length === 0) return leftOut;
+	const options = {
+		mode: "server",
+		...kept.sample === null ? {} : { initialValue: kept.sample }
+	};
+	const now = runScenarios(after.schema, kept.scenarios, options);
+	const { regressions } = comparedToLastRun(runScenarios(before.schema, kept.scenarios, options), now);
+	return [...regressions.map((name) => {
+		const failures = now.find((result) => result.name === name)?.failures ?? [];
+		return `The example "${name}" held against version ${String(before.version)} and does not hold against version ${String(after.version)}: ${failures.map((failure) => failure.detail).join(" ")}`;
+	}), ...leftOut];
+}
+function asExamples(scenarios, sample) {
+	return {
+		scenarios,
+		...sample === null ? {} : { sample }
+	};
+}
+/** `{ scenarios, sample? }` from a request body, or a sentence for everything that is not. */
+function readExamplesBody(body) {
+	if (!isRecord(body) || !Array.isArray(body["scenarios"])) return { problems: ["Send { scenarios, sample? }, where scenarios is a list of examples."] };
+	const read = readList(body["scenarios"], body["sample"]);
+	return read.problems.length > 0 ? { problems: read.problems } : {
+		scenarios: read.scenarios,
+		sample: read.sample
+	};
+}
+/**
+* What a storage keeps, read as a list sent to be kept is read. The storage checks nothing
+* (`Storage.keepExamples`), so a row written around the use-case comes back here as it was
+* written, and only what reads as an example is handed on.
+*/
+function readKept(kept) {
+	if (kept === void 0) return {
+		scenarios: [],
+		sample: null,
+		problems: []
+	};
+	const items = kept.scenarios;
+	if (Array.isArray(items)) return readList(items, kept.sample);
+	const read = readList([], kept.sample);
+	return {
+		...read,
+		problems: ["What is kept as the examples is not a list of them.", ...read.problems]
+	};
+}
+/** Each item through `readScenario`, names once each, and the sample as answers by field. */
+function readList(items, sample) {
+	const problems = [];
+	if (sample !== void 0 && sample !== null && !isRecord(sample)) problems.push("The sample is the answers every example starts from, by field, and this is not that.");
+	const scenarios = [];
+	const first = /* @__PURE__ */ new Map();
+	items.forEach((item, index) => {
+		const position = index + 1;
+		const read = readScenario(item);
+		if (!read.ok) {
+			problems.push(`${which(position, read.problem.name)} ${SHAPE_PROBLEMS[read.problem.reason](read.problem)}`);
+			return;
+		}
+		const earlier = first.get(read.scenario.name);
+		if (earlier !== void 0) {
+			problems.push(`${which(position, read.scenario.name)} has the name of example ${String(earlier)}; a name is how an example's result is found.`);
+			return;
+		}
+		first.set(read.scenario.name, position);
+		scenarios.push(read.scenario);
+	});
+	return {
+		scenarios,
+		sample: isRecord(sample) ? sample : null,
+		problems
+	};
+}
+function which(position, name) {
+	return `Example ${String(position)}${name === void 0 ? "" : ` ("${name}")`}`;
+}
+/** What each reason `readScenario` gives means, said for whoever sent the list. */
+const SHAPE_PROBLEMS = {
+	"not-an-object": () => "is not an object.",
+	"unknown-key": ({ part }) => `has "${part ?? ""}", which an example does not have.`,
+	"no-name": () => "has no name.",
+	"no-changes": () => "has no \"changes\": the answers it sets, by field.",
+	"no-verdict": () => "does not say whether the form is \"valid\" afterwards, as true or false.",
+	malformed: ({ part }) => `has a "${part ?? ""}" of the wrong shape.`
+};
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
 //#region src/publishing.ts
 /**
 * Publish a schema as a form's next version.
@@ -1520,6 +1838,10 @@ async function publishForm(deps, input) {
 			version: already.version
 		};
 		const version = await deps.storage.latestVersionNumber(existing.id) + 1;
+		const stopped = await examplesThatStopHolding(deps.storage, existing.id, current, {
+			schema,
+			version
+		});
 		const versionId = deps.newId();
 		await deps.storage.publishVersion({
 			version: {
@@ -1542,7 +1864,7 @@ async function publishForm(deps, input) {
 			versionId,
 			version,
 			schemaHash: hash,
-			warnings
+			warnings: [...warnings, ...stopped]
 		};
 	}
 	if (input.basedOnSchemaHash !== void 0) return {
@@ -1600,6 +1922,7 @@ function publishAudit(deps, input, about) {
 			actorKind: input.actor.kind,
 			actorId: input.actor.id
 		},
+		...input.requestId === void 0 ? {} : { requestId: input.requestId },
 		detail: {
 			version: about.version,
 			schemaHash: about.hash,
@@ -1608,6 +1931,38 @@ function publishAudit(deps, input, about) {
 	};
 }
 //#endregion
-export { AUDIT_ACTIONS, BREAKER_COOLDOWN_MS, BREAKER_THRESHOLD, CHALLENGE_TTL_SECONDS, DEFAULT_MAX_NUMBER, EVENT_ID_HEADER, MAX_ATTEMPTS, SIGNATURE_HEADER, afterAttempt, afterWebhookAttempt, auditedBy, authenticateApiKey, authenticateLocal, breakerState, can, checkMembership, collectAbandonedFiles, createApiKey, createLocalUser, createMemoryStorage, createSubmission, decodeSolution, deliveryHeaders, drainOutbox, encodeSolution, exportCsv, fileFieldPaths, filesToClaim, hashOf, healthOf, isIpLiteral, isPrivateAddress, listForms, listSubmissions, listVersions, mayAttempt, mintChallenge, offerUpload, publishForm, replayDelivery, resolveForm, resumeDraft, retryDelayMs, saveDraft, screenUpload, setFormAccess, signBody, signedPayload, solveChallenge, sourceNamesIn, sourcedAnswers, startDraft, unsafePatterns, verifySignature, verifySolution };
+//#region src/model.ts
+/**
+* Ask the deployment's model a builder's request, under the briefing for its kind.
+*
+* Whatever else the request carries is not read — a `system` above all. Resolves on every
+* ending: an adapter that throws broke its contract, and is still a model that could not
+* be asked.
+*/
+async function completeBuilderRequest(completer, request, cancellation) {
+	const { kind, user } = request;
+	if (!isModelRequestKind(kind)) return {
+		ok: false,
+		failure: "unknown_kind"
+	};
+	if (typeof user !== "string" || user.trim() === "") return {
+		ok: false,
+		failure: "no_user"
+	};
+	try {
+		return await completer.complete({
+			system: modelBriefing(kind),
+			user
+		}, cancellation);
+	} catch (error) {
+		return {
+			ok: false,
+			failure: "unavailable",
+			cause: error instanceof Error ? error.message : String(error)
+		};
+	}
+}
+//#endregion
+export { AUDIT_ACTIONS, BREAKER_COOLDOWN_MS, BREAKER_THRESHOLD, CHALLENGE_TTL_SECONDS, DEFAULT_MAX_NUMBER, EVENT_ID_HEADER, MAX_ATTEMPTS, SIGNATURE_HEADER, afterAttempt, afterWebhookAttempt, auditedBy, authenticateApiKey, authenticateLocal, breakerState, can, checkMembership, collectAbandonedFiles, completeBuilderRequest, createApiKey, createLocalUser, createMemoryStorage, createSubmission, decodeSolution, deliveryHeaders, drainOutbox, encodeSolution, exportCsv, fileFieldPaths, filesToClaim, formToFill, hashOf, healthOf, isIpLiteral, isPrivateAddress, keepExamples, listForms, listSubmissions, listVersions, mayAttempt, mintChallenge, offerUpload, publishForm, readExamples, replayDelivery, resolveForm, resumeDraft, retryDelayMs, saveDraft, screenUpload, setFormAccess, signBody, signedPayload, solveChallenge, sourceNamesIn, sourcedAnswers, startDraft, unsafePatterns, verifySignature, verifySolution };
 
 //# sourceMappingURL=index.mjs.map