@formancy/server-core 0.7.0 → 0.8.0

package/dist/index.mjs

@@ -8,14 +8,6 @@ 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 }`.
-*
-* Walked from the SCHEMA over the value, never from the value's own shape — the
-* same way `referencedFileIds` does it. A walk driven by what arrived would let a
-* client dodge the check by omitting a property, and hidden branches have already
-* been stripped by the engine before this runs.
-*/
 function sourcedAnswers(schema, value) {
 	const found = [];
 	const walk = (fields, data, prefix) => {
@@ -43,12 +35,6 @@ function sourcedAnswers(schema, value) {
 	walk(schema.model.fields, value, "");
 	return found;
 }
-/**
-* Ask each source about the values submitted for it.
-*
-* One call per source rather than per answer, so a deployment sees `IN (…)` and not
-* a query per row.
-*/
 async function checkMembership(schema, value, sources) {
 	const answers = sourcedAnswers(schema, value);
 	if (answers.length === 0 || sources === void 0) return { ok: true };
@@ -92,11 +78,6 @@ async function checkMembership(schema, value, sources) {
 		errors
 	};
 }
-/**
-* The source names a document uses, for the publish-time vocabulary check.
-*
-* Walked over the schema rather than over any data, because publishing has none.
-*/
 function sourceNamesIn(schema) {
 	const names = /* @__PURE__ */ new Set();
 	const walk = (fields) => {
@@ -110,28 +91,6 @@ function sourceNamesIn(schema) {
 }
 //#endregion
 //#region src/audit.ts
-/**
-* Who did what, to which thing, and when.
-*
-* **Reads and exports are recorded as well as mutations** — `submission.read` and
-* `submission.exported` — which is what lets a self-hoster answer who downloaded four
-* thousand people's answers ([0057](../../../docs/decisions/0057-the-audit-log-records-reads.md)).
-*
-* **A row joins the mutation's transaction where there is one.** `insertSubmission` and
-* `publishVersion` both commit their audit row with the change it describes, so a
-* rollback leaves no trace saying it happened. A read has nothing to be atomic with, so
-* its row is appended after the rows are handed over and a failure to write it is logged
-* loudly rather than swallowed.
-*
-* **`detail` carries identifiers and counts, never submission content.** An audit log is
-* read by more people, kept longer and exported more freely than the data it describes.
-*/
-/**
-* Every auditable action, as a closed list.
-*
-* Closed so a new route cannot invent its own spelling: an audit log where one event is
-* called two things is one nobody can query.
-*/
 const AUDIT_ACTIONS = [
 	"auth.login",
 	"auth.login.failed",
@@ -148,13 +107,6 @@ const AUDIT_ACTIONS = [
 	"delivery.replayed",
 	"model.asked"
 ];
-/**
-* An entry from an actor, with the fields spread the way the record stores
-* them.
-*
-* A helper rather than a convention, because `actorKind` and `actorId` being
-* set together is exactly the sort of thing eleven call sites get wrong once.
-*/
 function auditedBy(actor, draft) {
 	return actor === void 0 ? draft : {
 		...draft,
@@ -164,38 +116,14 @@ function auditedBy(actor, draft) {
 }
 //#endregion
 //#region src/webhook.ts
-/**
-* What a webhook delivery looks like on the wire.
-*
-* The signature scheme is Stripe's, deliberately: receivers already have code
-* for it, and a scheme somebody has to implement from scratch is a scheme most
-* receivers will skip. Adopting a familiar one is the difference between a
-* verified webhook and a verified-in-principle one.
-*/
 const EVENT_ID_HEADER = "x-formancy-event-id";
 const SIGNATURE_HEADER = "x-formancy-signature";
-/**
-* The signed payload is `timestamp.body`, not `body`.
-*
-* Without the timestamp inside the signature, a signature captured once stays
-* valid forever and can be replayed. With it, a receiver can reject anything
-* older than its tolerance, and the signature covers the timestamp it is
-* checking — so the timestamp cannot be edited either.
-*/
 function signedPayload(timestampSeconds, body) {
 	return `${String(timestampSeconds)}.${body}`;
 }
-/** Hex HMAC-SHA256 over the signed payload. */
 function signBody(secret, timestampSeconds, body) {
 	return bytesToHex(hmac(sha256, utf8ToBytes(secret), utf8ToBytes(signedPayload(timestampSeconds, body))));
 }
-/**
-* The headers for one delivery attempt.
-*
-* The event id is stable across retries, which is what makes the receiver able
-* to be idempotent. Generating a fresh one per attempt would turn our retry
-* into their duplicate.
-*/
 function deliveryHeaders(input) {
 	return {
 		"content-type": "application/json",
@@ -204,12 +132,6 @@ function deliveryHeaders(input) {
 		"x-formancy-attempt": String(input.attempt)
 	};
 }
-/**
-* Verify a delivery the way a receiver would.
-*
-* Exported because a scheme nobody can check is a scheme nobody does check —
-* this is the reference implementation, and the test for our own signing.
-*/
 function verifySignature(input) {
 	const parts = new Map(input.header.split(",").map((part) => {
 		const at = part.indexOf("=");
@@ -222,85 +144,29 @@ function verifySignature(input) {
 	if (Math.abs(input.nowSeconds - timestamp) > tolerance) return false;
 	return timingSafeEqual(signBody(input.secret, timestamp, input.body), provided);
 }
-/**
-* Compare without leaking where the first difference is.
-*
-* `a === b` on a hex string returns as soon as two characters differ, and the
-* time it takes says how many leading characters were right — enough, over
-* many attempts, to recover a signature a byte at a time.
-*/
 function timingSafeEqual(a, b) {
 	if (a.length !== b.length) return false;
 	let difference = 0;
 	for (let index = 0; index < a.length; index += 1) difference |= a.charCodeAt(index) ^ b.charCodeAt(index);
 	return difference === 0;
 }
-/**
-* How long to wait before attempt n, in milliseconds.
-*
-* Exponential, capped, with jitter. The jitter is the part that matters at
-* scale: without it every delivery queued by the same outage retries at the
-* same instant, and the receiver coming back up is knocked over by the
-* thundering herd of everyone's retries.
-*/
 function retryDelayMs(attempt, random) {
 	const base = Math.min(3e4 * 2 ** (attempt - 1), 216e5);
 	return Math.floor(base * random());
 }
-/** Eight attempts reach roughly 24 hours with this schedule. */
 const MAX_ATTEMPTS = 8;
 //#endregion
 //#region src/breaker.ts
-/**
-* Stopping, when a destination has plainly stopped listening.
-*
-* Failure is counted per WEBHOOK as well as per delivery. Enough consecutive failures
-* and the breaker opens: nothing is attempted for that webhook until a cool-down passes,
-* then exactly one delivery goes through as a probe. It succeeds and the breaker closes;
-* it fails and the cool-down starts again.
-*
-* `consecutiveFailures` and `openedAt` live on the RECORD rather than in the worker's
-* memory, so the state survives a restart and can be shown on a screen — a self-hoster
-* has no operations team watching a dashboard
-* ([0058](../../../docs/decisions/0058-a-breaker-per-destination.md)).
-*
-* Everything here is a pure function of a record and a clock: decisions tangled into
-* network code can only be tested by making requests.
-*/
-/**
-* How many consecutive failures open the breaker.
-*
-* Three, not one. A single failure is a bad minute — a deploy, a timeout, a
-* receiver restarting — and opening on it would make every routine blip a
-* visible outage. Three in a row is a destination that is not coming back on
-* its own.
-*/
 const BREAKER_THRESHOLD = 3;
-/**
-* How long the breaker stays shut before one probe is allowed through.
-*
-* Five minutes: long enough that a restarting receiver is finished, short
-* enough that nobody notices the delay once it recovers. The retry schedule
-* handles patience within a delivery; this handles patience about a
-* destination.
-*/
 const BREAKER_COOLDOWN_MS = 3e5;
 function breakerState(webhook, now) {
 	if (webhook.consecutiveFailures < 3) return "closed";
 	if (webhook.openedAt === null) return "closed";
 	return now.getTime() - new Date(webhook.openedAt).getTime() >= 3e5 ? "half-open" : "open";
 }
-/** Whether a delivery for this webhook may be attempted now. */
 function mayAttempt(webhook, now) {
 	return breakerState(webhook, now) !== "open";
 }
-/**
-* The webhook's health after one attempt against it.
-*
-* A success always closes the breaker completely. Decaying the count instead
-* would leave a destination that fails twice for every success permanently
-* one blip from opening, and that destination is working.
-*/
 function afterWebhookAttempt(webhook, ok, now) {
 	if (ok) return {
 		...webhook,
@@ -349,19 +215,6 @@ function afterAttempt(delivery, outcome, now, random) {
 		lastError: reason
 	};
 }
-/**
-* Drain one batch of due deliveries.
-*
-* Returns how many were attempted, so a caller can decide whether to come back
-* immediately or wait. Deliberately one batch rather than a loop that runs
-* forever: the thing that decides *when* to run belongs to the host, and a
-* function that never returns cannot be tested.
-*/
-/**
-* Returns how many were ATTEMPTED — deliveries skipped because their
-* destination's breaker is open do not count, so a caller polling until the
-* queue is quiet does not spin on a dead endpoint.
-*/
 async function drainOutbox(deps, limit = 20) {
 	const now = deps.now();
 	const due = await deps.storage.claimDueDeliveries(now.toISOString(), limit);
@@ -430,14 +283,6 @@ async function replayDelivery(deps, id) {
 }
 //#endregion
 //#region src/access.ts
-/**
-* Whether this caller may submit this form at all, before any of the work.
-*
-* Every branch that is not an explicit permission returns false. An allowlist
-* that exists but does not name the origin refuses; an origin header that is
-* absent refuses, because absent is not the same as allowed; an empty
-* allowlist refuses everything, because a list of no origins is a list.
-*/
 function maySubmit(form, actor, origin) {
 	if (actor === "authenticated") return true;
 	if (form.accessSubmit !== "public") return false;
@@ -448,14 +293,6 @@ function maySubmit(form, actor, origin) {
 }
 //#endregion
 //#region src/uploads.ts
-/**
-* Agree where a file will go, and refuse it before a byte is sent.
-*
-* Checking here rather than after the upload is the difference between
-* refusing a 2 GB file and receiving one first. The browser's own `accept` and
-* size limits are a convenience for the person filling the form in; these are
-* the rule, because somebody posting to the endpoint directly has neither.
-*/
 async function offerUpload(deps, input) {
 	if (!maySubmit(input.form, input.actor, input.origin)) return {
 		ok: false,
@@ -497,16 +334,6 @@ async function offerUpload(deps, input) {
 		file
 	};
 }
-/**
-* Whether an upload's bytes may be kept.
-*
-* **Fail closed.** A scanner that cannot be asked refuses the file, the same as one that
-* found something: a deployment that configured a scanner did so to keep unscanned files
-* out, and its being down is not a reason to let one in. The person is told to try again,
-* and the field offers exactly that. Without a scanner every upload is kept, as it was
-* before there was one — a supported state, said in the documentation rather than here
-* ([0131](../../../docs/decisions/0131-an-upload-is-scanned-before-it-is-kept.md)).
-*/
 async function screenUpload(scanner, file, bytes) {
 	if (scanner === void 0) return { ok: true };
 	let verdict;
@@ -529,24 +356,6 @@ async function screenUpload(scanner, file, bytes) {
 		finding: verdict.finding
 	};
 }
-/**
-* Which files a submission may claim, checked but not yet claimed.
-*
-* The claiming itself is `insertSubmission`'s job, in the same call that
-* stores the submission, so one COMMIT decides both — the same reasoning
-* that put the webhook queue there. A submission exists if and only if the
-* files it names belong to it. Claiming separately gives the two failures
-* nobody can debug: a rolled-back submission leaving files claimed against
-* nothing, or an accepted submission referencing bytes the collector is about
-* to delete.
-*
-* Refuses rather than skips. A submission naming a file that does not exist,
-* belongs to another form, or is already claimed is not a submission to fix up
-* quietly: the first is a bug or somebody guessing ids; the second is how an
-* id from a form you may submit to would let you attach a file from one you
-* may not; the third would make deleting a submission either leak bytes or
-* break a different one.
-*/
 async function filesToClaim(storage, input) {
 	const ids = referencedFileIds(input.schema, input.data);
 	if (ids.length === 0) return {
@@ -572,19 +381,10 @@ async function filesToClaim(storage, input) {
 		ids: claimable.map((file) => file.id)
 	};
 }
-/**
-* Files nobody claimed, old enough that nobody is going to.
-*
-* Returns the rows rather than deleting anything: the host removes the bytes
-* and then the rows, in that order, because a row without bytes is a broken
-* reference and bytes without a row are invisible rubbish. Of the two, the
-* second is the one you never find out about.
-*/
 async function collectAbandonedFiles(storage, now, afterHours) {
 	const before = (/* @__PURE__ */ new Date(now.getTime() - afterHours * 36e5)).toISOString();
 	return storage.abandonedFiles(before);
 }
-/** The field at a data path, with `[]` treated as "inside this repeater". */
 function fileFieldAt(schema, path) {
 	const segments = path.replace(/\[\]/g, "").split(".").filter((segment) => segment !== "");
 	let fields = flattenPages(schema.model.fields);
@@ -596,14 +396,12 @@ function fileFieldAt(schema, path) {
 	}
 	return found;
 }
-/** A page contributes no segment to a data path. */
 function flattenPages(fields) {
 	const out = [];
 	for (const field of fields) if (field.type === "page") out.push(...flattenPages(field.fields ?? []));
 	else out.push(field);
 	return out;
 }
-/** The HTML `accept` grammar, as the engine reads it. */
 function accepted(accept, name, contentType) {
 	if (accept === void 0 || accept.length === 0) return true;
 	const lowerName = name.toLowerCase();
@@ -616,20 +414,6 @@ function accepted(accept, name, contentType) {
 		return lowerType === rule;
 	});
 }
-/**
-* Every file id a submission references.
-*
-* Driven by the SCHEMA, not by the shape of the values. Recognising an
-* attachment by "an object with an id" would let a client omit a property and
-* have its reference quietly not claimed — the submission would be accepted
-* carrying a dangling file id, and the collector would delete the bytes a day
-* later. Reading only the paths the model says are file fields cannot be
-* fooled that way, and a text answer that happens to look like a file is not
-* one.
-*
-* A repeater contributes rows the schema cannot know about, so the walk
-* expands over whatever rows the data actually has.
-*/
 function referencedFileIds(schema, data) {
 	const ids = [];
 	const walk = (fields, value) => {
@@ -655,68 +439,26 @@ function referencedFileIds(schema, data) {
 	walk(schema.model.fields, data);
 	return ids;
 }
-/** Re-exported so a host can see which paths a schema's file fields live at. */
 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;
@@ -738,13 +480,6 @@ async function resolveForm(deps, path) {
 		schemaHash: current.schemaHash
 	};
 }
-/**
-* Change who may submit a form, and from where.
-*
-* Separate from publishing on purpose: access is a property of the deployment,
-* and changing it must not mint a new immutable form version or invalidate the
-* schema hash every client is holding.
-*/
 async function setFormAccess(deps, input) {
 	const form = await deps.storage.getFormByPath(input.path);
 	if (form === void 0) return { ok: false };
@@ -754,9 +489,6 @@ async function setFormAccess(deps, input) {
 	});
 	return { ok: true };
 }
-/** 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. */
 async function listSubmissions(deps, path) {
 	const form = await deps.storage.getFormByPath(path);
 	if (form === void 0) return void 0;
@@ -769,16 +501,6 @@ async function listSubmissions(deps, path) {
 		data: record.data
 	}));
 }
-/**
-* Every submission of a form as CSV, columns UNIONED across schema versions:
-* the current version's columns lead in its own order, and columns that only
-* exist in older versions follow — data outlives the field that collected it,
-* and an export that silently dropped extinct columns would lose it.
-*
-* A repeater is one column carrying its rows as JSON: rows-per-cell beats
-* exploding one submission across several CSV lines, which breaks every
-* spreadsheet join a business user will try.
-*/
 async function exportCsv(deps, path) {
 	const form = await deps.storage.getFormByPath(path);
 	if (form === void 0) return void 0;
@@ -808,8 +530,6 @@ async function exportCsv(deps, path) {
 	}
 	return lines.join("\n") + "\n";
 }
-/** One column per collected answer: leaves as dotted paths through groups,
-*  a repeater as a single column, pages transparent as always. */
 function dataColumns(schema) {
 	const columns = [];
 	const walk = (fields, prefix) => {
@@ -820,8 +540,6 @@ function dataColumns(schema) {
 	walk(schema.model.fields, "");
 	return columns;
 }
-/** The answer a submission holds at a column, read as the engine reads one: its own, so an
-*  unanswered `constructor` is an empty cell and not `function Object` (0185). */
 function cellValue(data, column) {
 	const current = getAt(data, column.split("."));
 	if (current === void 0 || current === null) return "";
@@ -832,18 +550,6 @@ function cellValue(data, column) {
 function csvCell(value) {
 	return /[",\n\r]/.test(value) ? `"${value.replaceAll("\"", "\"\"")}"` : value;
 }
-/**
-* 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);
 	if (current === void 0) return void 0;
@@ -854,8 +560,6 @@ async function startDraft(deps, input) {
 		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;
@@ -875,18 +579,6 @@ async function saveDraft(deps, input) {
 		saved: true
 	};
 }
-/**
-* Resume a draft — and migrate it LAZILY if the form was republished since,
-* which is versioning rule five: never migrate eagerly on publish, because
-* most drafts are abandoned and eager migration multiplies every publish by
-* every draft.
-*
-* diffSchemas drives the decision: `compatible` rebinds silently, `lossy`
-* rebinds with a report — declared renames carry their value to the new key,
-* removed fields move their value into `__orphaned` rather than deleting it —
-* and `breaking` refuses to rebind at all. A successful rebind is persisted,
-* so the migration runs once, not on every resume.
-*/
 async function resumeDraft(deps, input) {
 	const current = await resolveForm(deps, input.path);
 	if (current === void 0) return void 0;
@@ -978,8 +670,6 @@ function applyRenames(fields, data) {
 		if (field.type === "group" && typeof held === "object" && held !== null) applyRenames(field.fields ?? [], held);
 	}
 }
-/** Remove and return the value at a dotted path, pruning nothing else — what the draft
-*  holds there as its own, never what every object inherits. */
 function takeAtDottedPath(data, dottedPath) {
 	const segments = dottedPath.split(".");
 	const parent = getAt(data, segments.slice(0, -1));
@@ -989,12 +679,9 @@ function takeAtDottedPath(data, dottedPath) {
 	delete parent[last];
 	return value;
 }
-/** JSON-safe deep clone: draft data is JSON by construction, and this package
-*  runs without structuredClone in its lib on purpose. */
 function structuredCloneJson(value) {
 	return JSON.parse(JSON.stringify(value));
 }
-/** Every form with its current version — the admin's landing view. */
 async function listForms(deps) {
 	const forms = await deps.storage.listForms();
 	const listed = [];
@@ -1011,8 +698,6 @@ async function listForms(deps) {
 	}
 	return listed;
 }
-/** A form's version history, newest first — metadata only, because a history
-*  view rendering fifty full schemas would be its own denial of service. */
 async function listVersions(deps, path) {
 	const form = await deps.storage.getFormByPath(path);
 	if (form === void 0) return void 0;
@@ -1022,17 +707,30 @@ async function listVersions(deps, path) {
 		title: version.schema.title
 	}));
 }
+async function formVersion(deps, path, version) {
+	const form = await deps.storage.getFormByPath(path);
+	if (form === void 0) return {
+		ok: false,
+		kind: "unknown_form"
+	};
+	if (!/^[1-9]\d{0,8}$/.test(version)) return {
+		ok: false,
+		kind: "unknown_version"
+	};
+	const found = (await deps.storage.listVersionsByForm(form.id)).find((candidate) => candidate.version === Number(version));
+	if (found === void 0) return {
+		ok: false,
+		kind: "unknown_version"
+	};
+	return {
+		ok: true,
+		version: found.version,
+		schemaHash: found.schemaHash,
+		schema: found.schema
+	};
+}
 //#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;
@@ -1041,20 +739,6 @@ async function formToFill(deps, path) {
 		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 {
@@ -1098,7 +782,7 @@ async function createSubmission(deps, input) {
 	};
 	const engine = createFormEngine({
 		schema: current.schema,
-		initialValue: input.data,
+		initialValue: input.data ?? {},
 		capabilities: deps.capabilities,
 		mode: "server",
 		...deps.checks === void 0 ? {} : { checks: deps.checks }
@@ -1178,7 +862,6 @@ async function createSubmission(deps, input) {
 }
 //#endregion
 //#region src/redos.ts
-/** Every `pattern` in the model, with the data path of the field it sits on. */
 function patternsIn(fields, prefix) {
 	const found = [];
 	for (const field of fields) {
@@ -1191,15 +874,6 @@ function patternsIn(fields, prefix) {
 	}
 	return found;
 }
-/**
-* The patterns in this schema that an attacker could exploit, or an empty array
-* when there are none.
-*
-* A pattern `recheck` cannot decide about is ACCEPTED. Refusing on `unknown`
-* would make publishing depend on an analysis timeout, which is a worse failure
-* than the one being prevented — an author whose legitimate form stops
-* publishing intermittently has no way to act on that.
-*/
 async function unsafePatterns(schema) {
 	const unsafe = [];
 	for (const { path, pattern } of patternsIn(schema.model.fields, "")) {
@@ -1216,11 +890,6 @@ async function unsafePatterns(schema) {
 }
 //#endregion
 //#region src/testing/memory-storage.ts
-/**
-* The in-memory Storage — the second implementation that keeps the port
-* honest, and the one unit tests run against. Deliberately dumb: Maps and
-* scans, no cleverness to accidentally diverge from SQL semantics.
-*/
 function createMemoryStorage() {
 	const forms = /* @__PURE__ */ new Map();
 	const webhooks = /* @__PURE__ */ new Map();
@@ -1412,11 +1081,6 @@ async function createLocalUser(deps, input) {
 		id
 	};
 }
-/**
-* A wrong password and an unknown email answer identically, and BOTH run a
-* hash verification — the difference in shape or timing would be a
-* user-enumeration oracle.
-*/
 async function authenticateLocal(deps, input) {
 	const user = await deps.storage.getUserByEmail(input.email);
 	const hash = user?.passwordHash ?? await deps.hashSecret(`decoy:${deps.newId()}`);
@@ -1431,8 +1095,6 @@ async function authenticateLocal(deps, input) {
 		}
 	};
 }
-/** The visible prefix of an API key: enough to index and to name in a UI
-*  ("fmc_tok_a2c…"), never enough to authenticate. */
 const KEY_PREFIX_LENGTH = 12;
 async function createApiKey(deps, input) {
 	if (input.name.trim() === "") return {
@@ -1493,26 +1155,6 @@ function can(actor, action) {
 }
 //#endregion
 //#region src/address.ts
-/**
-* Deciding whether an address is somewhere this server may fetch from.
-*
-* A self-hosted formancy sits inside somebody's private network and webhook
-* URLs are written by whoever can edit a form, which makes the server a
-* confused deputy: it can reach the database, the metadata service and every
-* internal admin panel, and it will fetch whatever it is told to.
-*
-* This half is pure — given an address, is it private — so it lives here and is
-* tested exhaustively. The rest lives in @formancy/server, because it cannot be
-* pure: parsing a URL needs `URL`, and resolving a hostname then connecting to
-* the address that was checked, rather than re-resolving, needs Node's DNS and
-* a custom agent. This package has no @types/node by design, and hand-rolling
-* a URL parser for a security check is how such a check gets quietly wrong.
-* All three parts are necessary. Validating a URL and then handing it to fetch is defeated by DNS
-* rebinding — the name resolves to a public address for the check and a private
-* one for the request — and that is the difference between a mitigation and
-* theatre.
-*/
-/** Everything before the first dot, as four octets, or undefined. */
 function ipv4Octets(address) {
 	const parts = address.split(".");
 	if (parts.length !== 4) return void 0;
@@ -1523,12 +1165,6 @@ function ipv4Octets(address) {
 	if (octets.some((octet) => Number.isNaN(octet) || octet > 255)) return void 0;
 	return octets;
 }
-/**
-* Whether this address is one the server must not be pointed at.
-*
-* Unparseable input counts as private. An address this cannot classify is one
-* it cannot vouch for, and the safe direction is refusing to fetch.
-*/
 function isPrivateAddress(address) {
 	const trimmed = address.trim().toLowerCase();
 	if (trimmed === "") return true;
@@ -1559,14 +1195,6 @@ function isPrivateAddress(address) {
 	}
 	return true;
 }
-/**
-* Whether this is a literal IP address rather than a hostname.
-*
-* The two need different treatment and conflating them breaks the check in
-* both directions: `isPrivateAddress` fails closed on anything it cannot
-* parse, which is correct for an address that came back from DNS and wrong for
-* `example.ch`, where it would refuse every hostname in the world.
-*/
 function isIpLiteral(host) {
 	const bare = host.trim().replace(/^\[|\]$/g, "");
 	if (/^\d{1,3}(\.\d{1,3}){3}$/.test(bare)) return true;
@@ -1574,7 +1202,6 @@ function isIpLiteral(host) {
 }
 //#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,
@@ -1594,14 +1221,6 @@ async function readExamples(deps, input) {
 		}
 	};
 }
-/**
-* 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,
@@ -1641,23 +1260,6 @@ async function keepExamples(deps, input) {
 		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));
@@ -1680,7 +1282,6 @@ function asExamples(scenarios, sample) {
 		...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"]);
@@ -1689,11 +1290,6 @@ function readExamplesBody(body) {
 		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: [],
@@ -1708,7 +1304,6 @@ function readKept(kept) {
 		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.");
@@ -1738,7 +1333,6 @@ function readList(items, sample) {
 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.`,
@@ -1752,15 +1346,6 @@ function isRecord(value) {
 }
 //#endregion
 //#region src/publishing.ts
-/**
-* Publish a schema as a form's next version.
-*
-* This is the save gate: structural validation, then the ENGINE's own compile
-* — type-checked expressions, kind policies and the cycle graph — so a form
-* that can loop or read a ghost field is refused here and never persisted.
-* Republishing the identical document is idempotent, because "deploy again"
-* must never manufacture a version.
-*/
 async function publishForm(deps, input) {
 	const validated = validateSchema(input.schema);
 	if (!validated.valid) return {
@@ -1899,14 +1484,6 @@ async function publishForm(deps, input) {
 		warnings
 	};
 }
-/**
-* The audit row for a publish, built here so it can travel INSIDE the
-* transaction rather than being appended after it.
-*
-* Before this it was written by the route once all three storage calls had
-* returned, which meant a publish could half-apply and still be recorded as
-* having happened. Now it rolls back with everything else.
-*/
 function publishAudit(deps, input, about) {
 	return {
 		id: deps.newId(),
@@ -1927,13 +1504,6 @@ function publishAudit(deps, input, about) {
 }
 //#endregion
 //#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 {
@@ -1958,6 +1528,6 @@ async function completeBuilderRequest(completer, request, cancellation) {
 	}
 }
 //#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 };
+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, formVersion, 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