@formancy/server-core 0.3.0 → 0.5.0

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { CHALLENGE_TTL_SECONDS, Challenge, DEFAULT_MAX_NUMBER, Solution, VerifyOutcome, decodeSolution, encodeSolution, hashOf, mintChallenge, solveChallenge, verifySolution } from "@formancy/challenge";
+import { CapabilitySource, Check, Scenario } from "@formancy/core";
 import { Change, FormSchema } from "@formancy/spec";
-import { CapabilitySource, Check } from "@formancy/core";
 import { SchemaError } from "@formancy/spec/validate";
 //#region src/options-membership.d.ts
 /**
@@ -220,8 +220,37 @@ interface FileRecord {
   createdAt: string;
   /** The submission that claimed it, or null. One file, one submission. */
   submissionId: string | null;
+  /**
+   * Until when one request holds the right to receive this file's bytes, or null when
+   * none does. Not a fourth state: the file is still `offered` while it is received, and
+   * a lease that has run out is no lease. See `leaseFile`.
+   */
+  receivingUntil: string | null;
+}
+/**
+ * A form's examples, and the fictional sample every one of them starts from — the pair the
+ * starter templates carry as `*.scenarios.json` and `*.sample.json`
+ * ([0166](../../../docs/decisions/0166-a-deployment-keeps-a-forms-examples-and-runs-them-at-publish.md)).
+ *
+ * Beside the form and not inside a version. A published version is immutable
+ * ([0025](../../../docs/decisions/0025-immutability-in-the-database.md)), and examples change
+ * while the form does not: written into a version, every example added would mint one. One
+ * record per form, replaced whole, because the scenario panes hand back the whole list.
+ */
+interface ExamplesRecord {
+  formId: string;
+  scenarios: readonly Scenario[];
+  /** Where every example starts, or null when none was kept. */
+  sample: Readonly<Record<string, unknown>> | null;
+  updatedAt: string;
 }
 interface Storage {
+  /**
+   * The form at this path, or `undefined` for a path no form has — one holding a character this
+   * storage cannot keep included, such as a NUL in PostgreSQL's `text`. It arrives from a URL, as
+   * anybody wrote it, so it is an unknown form and never an error. `getDraft`, `getUserByEmail`
+   * and `findApiKeysByPrefix` find none the same way: what they look up arrives from a request too.
+   */
   getFormByPath(path: string): Promise<FormRecord | undefined>;
   listForms(): Promise<FormRecord[]>;
   createForm(record: FormRecord): Promise<void>;
@@ -252,6 +281,17 @@ interface Storage {
     audit?: AuditEntry;
   }): Promise<void>;
   getVersionById(id: string): Promise<FormVersionRecord | undefined>;
+  /** A form's examples, or undefined when none were ever kept for it. */
+  getExamples(formId: string): Promise<ExamplesRecord | undefined>;
+  /**
+   * Replace a form's examples and sample, with the audit row, in ONE commit — as a publish
+   * carries its own: a change that rolled back must leave nothing saying it happened.
+   *
+   * The form must exist; the PostgreSQL storage has the database refuse one that does not.
+   * Nothing here reads the examples: whether they are examples is the use-case's question,
+   * asked before this is called, and again of what `getExamples` hands back.
+   */
+  keepExamples(record: ExamplesRecord, audit?: AuditEntry): Promise<void>;
   findVersionByHash(formId: string, schemaHash: string): Promise<FormVersionRecord | undefined>;
   latestVersionNumber(formId: string): Promise<number>;
   /**
@@ -269,8 +309,23 @@ interface Storage {
    * prevents — a webhook fired for a rolled-back submission, a stored
    * submission nothing was sent about, an accepted submission whose files the
    * collector deletes — are the ones a self-hoster cannot debug.
+   *
+   * Returns false, and writes NOTHING — no delivery, no claim, no audit row — when a
+   * submission with `record.id` is already stored. The id is the one a response's token
+   * names, so that is the same response sent twice
+   * ([0169](../../../docs/decisions/0169-a-response-is-stored-once.md)). ATOMIC, as
+   * `spendChallenge` is and for its reason: two sends of one response both pass every check
+   * made before this, and only the storage can decide which is stored.
    */
-  insertSubmission(record: SubmissionRecord, deliveries?: readonly DeliveryRecord[], claimFileIds?: readonly string[], audit?: AuditEntry): Promise<void>;
+  insertSubmission(record: SubmissionRecord, deliveries?: readonly DeliveryRecord[], claimFileIds?: readonly string[], audit?: AuditEntry): Promise<boolean>;
+  /**
+   * Whether a submission with this id is stored.
+   *
+   * Asked before the replay, so a response sent again is told it was sent — rather than that
+   * the files it names are unknown, which is what the claim would say of files the first send
+   * already took. `insertSubmission` still decides: two sends at once both find nothing here.
+   */
+  hasSubmission(id: string): Promise<boolean>;
   /**
    * Append one audit row.
    *
@@ -305,8 +360,42 @@ interface Storage {
   /** Drop spent challenges that can no longer be replayed anyway. */
   forgetExpiredChallenges(beforeIso: string): Promise<number>;
   insertFile(record: FileRecord): Promise<void>;
+  /**
+   * The file with this id, or `undefined` for an id no file has — one in no shape this storage's
+   * ids take included. It arrives from a URL and from a response, as anybody wrote it, so it is an
+   * unknown file and never an error.
+   */
   getFile(id: string): Promise<FileRecord | undefined>;
-  updateFile(record: FileRecord): Promise<void>;
+  /**
+   * Take the right to receive an `offered` file's bytes, until `untilIso`.
+   *
+   * Returns false when the file is not `offered`, or another request holds a lease that
+   * has not run out at `nowIso`. ATOMIC, as `spendChallenge` is and for its reason: two
+   * requests carrying bytes for one file both pass every check made before this, and only
+   * the storage can decide which of them receives. A lease that reads and then writes hands
+   * the file to both, and the second writes its bytes over the first's.
+   *
+   * `untilIso` is also the lease's name, handed back to `settleFile` and `releaseFile`. No
+   * two requests can hold one at once: a lease is taken only once the last has run out,
+   * so the next always runs out later.
+   */
+  leaseFile(id: string, nowIso: string, untilIso: string): Promise<boolean>;
+  /**
+   * The bytes are kept: `stored`, and the lease cleared — only while the file is `offered`
+   * and the lease named `untilIso` still holds it. Returns false and changes nothing
+   * otherwise.
+   *
+   * It sets the state and nothing else. Its predecessor wrote back the whole record the
+   * request had read before its scan, so a request that outlasted a faster one put a
+   * claimed file back to `stored` with no submission, for the collector to delete.
+   */
+  settleFile(id: string, untilIso: string): Promise<boolean>;
+  /**
+   * Give the lease back without keeping anything, so the retry a refusal invites is not
+   * refused as busy. Only the lease named `untilIso`: a request that outlasted its own
+   * must not free the one that took over.
+   */
+  releaseFile(id: string, untilIso: string): Promise<boolean>;
   /** Every file in a state other than `claimed`, created before `beforeIso`. */
   abandonedFiles(beforeIso: string): Promise<FileRecord[]>;
   deleteFiles(ids: readonly string[]): Promise<void>;
@@ -323,6 +412,7 @@ interface Storage {
    * a table nobody looks at, which is the same as not having it.
    */
   deadDeliveries(limit: number): Promise<DeliveryRecord[]>;
+  /** As `getFile`: `undefined` for an id no delivery has, whatever its shape, since it arrives from a URL. */
   getDelivery(id: string): Promise<DeliveryRecord | undefined>;
   /** Oldest first, only those due. */
   claimDueDeliveries(nowIso: string, limit: number): Promise<DeliveryRecord[]>;
@@ -438,7 +528,7 @@ export declare function can(actor: Actor, action: Action): boolean;
  * 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.
  */
-export declare const AUDIT_ACTIONS: readonly ["auth.login", "auth.login.failed", "form.published", "form.access.changed", "submission.created", "submission.read", "submission.exported", "file.downloaded", "user.created", "apiKey.created", "apiKey.revoked", "delivery.replayed"];
+export declare const AUDIT_ACTIONS: readonly ["auth.login", "auth.login.failed", "form.published", "form.access.changed", "form.examples.changed", "submission.created", "submission.read", "submission.exported", "file.downloaded", "user.created", "apiKey.created", "apiKey.revoked", "delivery.replayed", "model.asked"];
 type AuditAction = (typeof AUDIT_ACTIONS)[number];
 interface AuditEntry {
   readonly id: string;
@@ -458,7 +548,9 @@ interface AuditEntry {
   readonly subject?: string;
   /**
    * The request it happened in, so an export and the rows it returned can be
-   * tied together later.
+   * tied together later — and a row to the line a server's request log wrote
+   * for that request. A use-case that writes its row inside its transaction
+   * takes the id in its input, and names it when it is given one.
    */
   readonly requestId?: string;
   /** Identifiers and counts. Never a submission's answers. */
@@ -606,13 +698,158 @@ interface WebhookHealth {
 }
 export declare function healthOf(webhook: WebhookRecord, now: Date): WebhookHealth;
 //#endregion
-//#region src/use-cases.d.ts
+//#region src/uploads.d.ts
 /**
- * The backend's use-cases, framework-free.
+ * The file lifecycle: offered, stored, claimed, collected.
  *
- * Identity and time are injected like every other capability: the server pins
- * one clock per request, so a submission can be replayed later and produce the
- * same computed values byte for byte. Nothing here reads Date.now or crypto.
+ * **Bytes are not the submission's problem.** A submission stores what each
+ * file is and where it went, never the bytes themselves, so a submission read
+ * back years later is small, self-describing, and still says what was attached
+ * even if the object store has since been emptied.
+ *
+ * **The claim happens inside the submission's transaction.** A submission
+ * exists if and only if the files it names are claimed against it. Anything
+ * looser gives one of the two failures nobody can debug: a rolled-back
+ * submission leaving files claimed against nothing, or an accepted submission
+ * referencing files the collector is about to delete.
+ *
+ * **Nothing here touches a disk.** This package has no filesystem and no
+ * object store; it decides what is rubbish and the host deletes it. That is
+ * the same split every other port here makes, and it is why the whole
+ * lifecycle is testable without either.
+ */
+interface OfferDeps {
+  storage: Storage;
+  now: () => Date;
+  newId: () => string;
+}
+interface OfferInput {
+  schema: FormSchema;
+  /** The form, for the access check — the same one a submission passes. */
+  form: FormRecord;
+  actor: 'anonymous' | 'authenticated';
+  origin: string | undefined;
+  /** The field the file is for, as a data path: `evidence`, `people[].passport`. */
+  field: string;
+  name: string;
+  size: number;
+  contentType: string;
+}
+type OfferOutcome = {
+  ok: true;
+  file: FileRecord;
+} | {
+  ok: false;
+  reason: 'not_allowed' | 'unknown_field' | 'not_a_file_field' | 'too_large' | 'not_accepted';
+};
+/**
+ * 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.
+ */
+export declare function offerUpload(deps: OfferDeps, input: OfferInput): Promise<OfferOutcome>;
+/** What a deployment's scanner says about an upload's bytes. */
+type ScanVerdict = {
+  clean: true;
+} | {
+  clean: false;
+  finding: string;
+};
+/**
+ * A deployment's virus scanner, asked about an upload's bytes before they are kept.
+ *
+ * A port because the deployment supplies it and there are two: the ClamAV adapter in
+ * `@formancy/server`, and the doubles that test this decision. **Throwing means it could
+ * not be asked** — a connection refused, a timeout — and never that the file is clean.
+ */
+interface Scanner {
+  scan(file: {
+    name: string;
+    contentType: string;
+    size: number;
+  }, bytes: Uint8Array): Promise<ScanVerdict>;
+}
+type ScreenOutcome = {
+  ok: true;
+} | {
+  ok: false;
+  reason: 'refused';
+  finding: string;
+} |
+/** `cause` is for the operator's log, never for the client: it can name an address. */
+{
+  ok: false;
+  reason: 'scanner_unavailable';
+  cause: string;
+};
+/**
+ * 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)).
+ */
+export declare function screenUpload(scanner: Scanner | undefined, file: {
+  name: string;
+  contentType: string;
+  size: number;
+}, bytes: Uint8Array): Promise<ScreenOutcome>;
+type ClaimOutcome = {
+  ok: true;
+  ids: readonly string[];
+} | {
+  ok: false;
+  unknown: readonly string[];
+};
+/**
+ * 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.
+ */
+export declare function filesToClaim(storage: Storage, input: {
+  schema: FormSchema;
+  formId: string;
+  data: unknown;
+}): Promise<ClaimOutcome>;
+/**
+ * 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.
+ */
+export declare function collectAbandonedFiles(storage: Storage, now: Date, afterHours: number): Promise<FileRecord[]>;
+/** Re-exported so a host can see which paths a schema's file fields live at. */
+export declare function fileFieldPaths(schema: FormSchema): string[];
+//#endregion
+//#region src/deps.d.ts
+/**
+ * What a deployment supplies to the use-cases: storage, identity, time, and the
+ * answers a document may only name — checks, lists and a scanner.
+ *
+ * Its own file because it is the one contract every use-case family shares, and
+ * `use-cases.ts` is where the families used to live; it moved when that file's size
+ * budget refused the scanner.
  */
 interface ServerDeps {
   storage: Storage;
@@ -630,13 +867,16 @@ interface ServerDeps {
   /** The clock/randomness the ENGINE sees during replay. */
   capabilities: CapabilitySource;
   /**
-   * Signs the token that proves somebody started a draft.
+   * Signs the keys the public plane hands out: the one that proves somebody started a
+   * draft, and the token a response is sent with so that it is stored once (0169).
    *
    * The public plane is anonymous, so a draft has no account behind it — which
    * is exactly why it needs a secret of its own. The host's own signing key is
    * reused rather than a second one being configured: a draft token is a
    * server-signed bearer token, which is what that key is already for, and an
    * optional secret would mean drafts are unprotected whenever nobody set it.
+   * Named for the first of the two; renaming it would break every host that builds
+   * these deps, for a word.
    */
   draftSecret: string;
   /**
@@ -654,7 +894,21 @@ interface ServerDeps {
    * legitimate configuration, and the reason the guarantee is written down.
    */
   optionsSources?: ServerOptionsSources;
+  /**
+   * The deployment's virus scanner, asked about every upload's bytes before they are
+   * kept. Absent means none is asked — a supported state, and the documented one.
+   */
+  scanner?: Scanner;
 }
+//#endregion
+//#region src/use-cases.d.ts
+/**
+ * The backend's use-cases, framework-free.
+ *
+ * Identity and time are injected like every other capability: the server pins
+ * one clock per request, so a submission can be replayed later and produce the
+ * same computed values byte for byte. Nothing here reads Date.now or crypto.
+ */
 interface ResolvedForm {
   formId: string;
   versionId: string;
@@ -663,48 +917,6 @@ interface ResolvedForm {
   schemaHash: string;
 }
 export declare function resolveForm(deps: ServerDeps, path: string): Promise<ResolvedForm | undefined>;
-type SubmissionOutcome = {
-  ok: true;
-  id: string;
-  canonicalData: unknown;
-} | {
-  ok: false;
-  kind: 'unknown_form';
-} | {
-  ok: false;
-  kind: 'version_changed';
-  current?: ResolvedForm;
-} | {
-  ok: false;
-  kind: 'invalid';
-  errors: Record<string, string[]>;
-} |
-/** The caller may not submit this form: not public, or not from this origin. */
-{
-  ok: false;
-  kind: 'forbidden';
-} |
-/**
- * A source that should have vouched for an answer could not.
- *
- * Failed closed and never accepted unchecked: a bogus value that is stored is
- * undetectable afterwards, while a refusal is retryable and the draft still holds
- * the answers.
- */
-{
-  ok: false;
-  kind: 'source_unavailable';
-  source: string;
-};
-/**
- * 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.
  *
@@ -719,14 +931,6 @@ export declare function setFormAccess(deps: ServerDeps, input: {
 }): Promise<{
   ok: boolean;
 }>;
-export declare function createSubmission(deps: ServerDeps, input: {
-  path: string;
-  declaredSchemaHash: string;
-  data: unknown;
-  /** Defaults to anonymous: the caller must prove otherwise, not the reverse. */
-  actor?: 'anonymous' | 'authenticated';
-  origin?: string;
-}): Promise<SubmissionOutcome>;
 interface ListedSubmission {
   id: string;
   version: number;
@@ -754,13 +958,21 @@ export declare function exportCsv(deps: ServerDeps, path: string): Promise<strin
  * 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.
  */
 export declare function startDraft(deps: ServerDeps, input: {
   path: string;
 }): Promise<{
   draftId: string;
   token: string;
+  submissionToken: string;
 } | undefined>;
+/** Save (or re-save) a partial form, bound to the CURRENT version. Undefined
+ *  for an unknown form. */
 export declare function saveDraft(deps: ServerDeps, input: {
   path: string;
   draftId: string;
@@ -782,6 +994,8 @@ type ResumeOutcome = {
   data: unknown;
   /** Present when the rebind lost something; absent for a silent rebind. */
   migration?: DraftMigration;
+  /** What the response is sent with: the same on every resume, naming the draft's id. */
+  submissionToken: string;
 } | {
   /** The schema changed in a way no automatic rebind survives: the draft
    *  comes back against ITS OWN version, and the caller offers a restart. */
@@ -824,6 +1038,110 @@ interface ListedVersion {
  *  view rendering fifty full schemas would be its own denial of service. */
 export declare function listVersions(deps: ServerDeps, path: string): Promise<ListedVersion[] | undefined>;
 //#endregion
+//#region src/submitting.d.ts
+/**
+ * Submitting a form: what a respondent is handed, the replay, and what is stored.
+ *
+ * Its own file because `use-cases.ts` named it as the next family to leave when its size
+ * budget refused growth, and the submission is what grew.
+ */
+type SubmissionOutcome = {
+  ok: true;
+  id: string;
+  canonicalData: unknown;
+} | {
+  ok: false;
+  kind: 'unknown_form';
+} | {
+  ok: false;
+  kind: 'version_changed';
+  current?: ResolvedForm;
+} | {
+  ok: false;
+  kind: 'invalid';
+  errors: Record<string, string[]>;
+} |
+/** The caller may not submit this form: not public, or not from this origin. */
+{
+  ok: false;
+  kind: 'forbidden';
+} |
+/**
+ * A source that should have vouched for an answer could not.
+ *
+ * Failed closed and never accepted unchecked: a bogus value that is stored is
+ * undetectable afterwards, while a refusal is retryable and the draft still holds
+ * the answers.
+ */
+{
+  ok: false;
+  kind: 'source_unavailable';
+  source: string;
+} |
+/** An anonymous response arrived without the token its form was handed out with. */
+{
+  ok: false;
+  kind: 'token_required';
+} |
+/**
+ * A token this server did not sign for this form: forged, another form's, or signed under
+ * a key the deployment no longer has. Loading the form again hands out a good one.
+ */
+{
+  ok: false;
+  kind: 'token_invalid';
+} |
+/** The response this token names is already stored, as `id`; nothing was stored again. */
+{
+  ok: false;
+  kind: 'token_spent';
+  id: string;
+};
+/** A published form as a respondent is handed it: its current version, and what to send it with. */
+interface FormToFill extends ResolvedForm {
+  /** Names the id the response will be stored under, signed for this form (0169). */
+  submissionToken: string;
+}
+/**
+ * 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)).
+ */
+export declare function formToFill(deps: ServerDeps, path: string): Promise<FormToFill | undefined>;
+/**
+ * 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)).
+ */
+export declare function createSubmission(deps: ServerDeps, input: {
+  path: string;
+  declaredSchemaHash: string;
+  data: unknown;
+  /** Defaults to anonymous: the caller must prove otherwise, not the reverse. */
+  actor?: 'anonymous' | 'authenticated';
+  origin?: string;
+  requestId?: string;
+  /**
+   * The token the form was handed out with. Required of an anonymous response. A signed-in
+   * one may leave it out and is stored under a fresh id, as before; one it sends is checked
+   * and spent like any other, because a token that is ignored when it is wrong is decoration.
+   */
+  token?: string;
+}): Promise<SubmissionOutcome>;
+//#endregion
 //#region src/redos.d.ts
 /**
  * Refuse a form whose `pattern` values can be made to backtrack.
@@ -968,101 +1286,6 @@ export declare function retryDelayMs(attempt: number, random: () => number): num
 /** Eight attempts reach roughly 24 hours with this schedule. */
 export declare const MAX_ATTEMPTS = 8;
 //#endregion
-//#region src/uploads.d.ts
-/**
- * The file lifecycle: offered, stored, claimed, collected.
- *
- * **Bytes are not the submission's problem.** A submission stores what each
- * file is and where it went, never the bytes themselves, so a submission read
- * back years later is small, self-describing, and still says what was attached
- * even if the object store has since been emptied.
- *
- * **The claim happens inside the submission's transaction.** A submission
- * exists if and only if the files it names are claimed against it. Anything
- * looser gives one of the two failures nobody can debug: a rolled-back
- * submission leaving files claimed against nothing, or an accepted submission
- * referencing files the collector is about to delete.
- *
- * **Nothing here touches a disk.** This package has no filesystem and no
- * object store; it decides what is rubbish and the host deletes it. That is
- * the same split every other port here makes, and it is why the whole
- * lifecycle is testable without either.
- */
-interface OfferDeps {
-  storage: Storage;
-  now: () => Date;
-  newId: () => string;
-}
-interface OfferInput {
-  schema: FormSchema;
-  /** The form, for the access check — the same one a submission passes. */
-  form: FormRecord;
-  actor: 'anonymous' | 'authenticated';
-  origin: string | undefined;
-  /** The field the file is for, as a data path: `evidence`, `people[].passport`. */
-  field: string;
-  name: string;
-  size: number;
-  contentType: string;
-}
-type OfferOutcome = {
-  ok: true;
-  file: FileRecord;
-} | {
-  ok: false;
-  reason: 'not_allowed' | 'unknown_field' | 'not_a_file_field' | 'too_large' | 'not_accepted';
-};
-/**
- * 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.
- */
-export declare function offerUpload(deps: OfferDeps, input: OfferInput): Promise<OfferOutcome>;
-type ClaimOutcome = {
-  ok: true;
-  ids: readonly string[];
-} | {
-  ok: false;
-  unknown: readonly string[];
-};
-/**
- * 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.
- */
-export declare function filesToClaim(storage: Storage, input: {
-  schema: FormSchema;
-  formId: string;
-  data: unknown;
-}): Promise<ClaimOutcome>;
-/**
- * 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.
- */
-export declare function collectAbandonedFiles(storage: Storage, now: Date, afterHours: number): Promise<FileRecord[]>;
-/** Re-exported so a host can see which paths a schema's file fields live at. */
-export declare function fileFieldPaths(schema: FormSchema): string[];
-//#endregion
 //#region src/publishing.d.ts
 /**
  * Publishing a form: the save gate, and who may overwrite whom.
@@ -1157,7 +1380,189 @@ export declare function publishForm(deps: ServerDeps, input: {
    * asks to be told it has been overtaken.
    */
   basedOnSchemaHash?: string;
+  /** The request this publish is answering, which its audit row names (`AuditEntry.requestId`). */
+  requestId?: string;
 }): Promise<PublishOutcome>;
 //#endregion
-export { type Action, type Actor, type AttemptOutcome, type AuditAction, type AuditDraft, type AuditEntry, type AuthDeps, type AuthOutcome, type BreakerState, CHALLENGE_TTL_SECONDS, type Challenge, type ClaimOutcome, DEFAULT_MAX_NUMBER, type DeliveryHeaders, type DeliveryRecord, type DraftMigration, type DraftRecord, type FileRecord, type FormRecord, type FormVersionRecord, type ListedForm, type ListedSubmission, type ListedVersion, type MembershipOutcome, type OfferDeps, type OfferInput, type OfferOutcome, type OutboxDeps, type PublishOutcome, type ReplayOutcome, type ResolvedForm, type ResumeOutcome, type Role, type ServerDeps, type ServerOptionsSource, type ServerOptionsSources, type Solution, type Storage, type SubmissionOutcome, type SubmissionRecord, type UnsafePattern, type VerifyOutcome, type WebhookHealth, type WebhookRecord, decodeSolution, encodeSolution, hashOf, mintChallenge, solveChallenge, verifySolution };
+//#region src/examples.d.ts
+/**
+ * A form's examples, kept by the deployment beside the form, and run when it is published
+ * ([0166](../../../docs/decisions/0166-a-deployment-keeps-a-forms-examples-and-runs-them-at-publish.md)).
+ *
+ * An example with its answer written down is the one check that tells a condition that
+ * compiles from the condition that was asked for
+ * ([0110](../../../docs/decisions/0110-a-form-is-checked-against-examples.md)). The builders
+ * run them, and the scenarios are the host's to keep
+ * ([0111](../../../docs/decisions/0111-a-scenario-panel-names-what-stopped-holding.md)); on a
+ * deployment the host is this server, so it keeps them, with the fictional sample they start
+ * from, and publishing — the last moment before a version is frozen — runs them.
+ *
+ * **The permission is decided here, not in the route.** Reading and changing a form's
+ * examples take what editing the form takes, `form.publish`, and a host composing its own
+ * HTTP over this package gets that rule with the use-case rather than having to remember it.
+ *
+ * **What is kept is read as what is sent is read**, by `readList`, on the way in and on the
+ * way out. A list sent to be kept with anything in it that is not an example keeps nothing; a
+ * row already kept that is not one — edited around `keepExamples` — is left out and named
+ * wherever the examples are read back, so the admin that draws them and the publish that runs
+ * them are only ever handed examples.
+ */
+/** A form's examples as a builder holds them: the list, and where every one starts. */
+interface FormExamples {
+  readonly scenarios: readonly Scenario[];
+  /** Absent when none was kept: every example then starts from an empty form. */
+  readonly sample?: Readonly<Record<string, unknown>>;
+  /**
+   * When they are read back: what is kept and is not an example, or not a sample, one sentence
+   * each. Left out of the above, so nothing draws or runs it, and gone at the next save, which
+   * keeps only what it is sent. Absent when everything kept could be read.
+   */
+  readonly unreadable?: readonly string[];
+}
+type ExamplesOutcome = {
+  readonly ok: true;
+  readonly examples: FormExamples;
+} |
+/** Not with this actor's role: a viewer may read the form, and not what it is checked against. */
+{
+  readonly ok: false;
+  readonly kind: 'forbidden';
+} |
+/** Examples are kept beside a form, so there must be one at this path. */
+{
+  readonly ok: false;
+  readonly kind: 'unknown_form';
+};
+type KeepExamplesOutcome = ExamplesOutcome |
+/** Something sent is not an example, or not a sample: one sentence each, and nothing kept. */
+{
+  readonly ok: false;
+  readonly kind: 'invalid_examples';
+  readonly problems: readonly string[];
+};
+/** The examples kept for the form at `path`; none, for a form nobody wrote any for. */
+export declare function readExamples(deps: ServerDeps, input: {
+  path: string;
+  actor: Actor;
+}): Promise<ExamplesOutcome>;
+/**
+ * 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.
+ */
+export declare function keepExamples(deps: ServerDeps,
+/** `requestId` is the request this change answers, which its audit row names. */
+input: {
+  path: string;
+  actor: Actor;
+  examples: unknown;
+  requestId?: string;
+}): Promise<KeepExamplesOutcome>;
+//#endregion
+//#region src/model.d.ts
+/**
+ * The deployment's own model, asked on a builder's behalf.
+ *
+ * The builders ask a model through an `AskModel` the host supplies, and a key in a browser
+ * is a key anybody who opens the page can read. So a deployment that has a model keeps it
+ * here, behind its own sessions, and the admin's `AskModel` is a request to this server
+ * ([0165](../../../docs/decisions/0165-a-deployments-model-is-asked-through-its-server.md)).
+ *
+ * **The server writes the briefing.** The browser names the kind of request — one of the
+ * three formancy makes — and sends the user part; the system part is the one
+ * `@formancy/builder-core` briefs that kind with, and one in the request is never read, so
+ * every request the operator's key pays for is asked under one of formancy's briefings.
+ * That narrows the endpoint; it does not close it. The user part is still the person's
+ * text, and nothing here stops it asking the model for something else under formancy's
+ * briefing: the permission, the rate limit, the size cap and the output limit bound what
+ * that costs, and the audit log says who asked.
+ */
+/** Everything a completion is asked: one system part and one user part, no conversation. */
+interface CompletionPrompt {
+  readonly system: string;
+  readonly user: string;
+}
+/**
+ * Told when whoever asked has gone, so the request is abandoned at the provider rather than
+ * paid for to the end.
+ *
+ * A callback rather than an `AbortSignal`, which this package's types do not have
+ * ([0008](../../../docs/decisions/0008-layered-packages.md)) — the shape builder-core's
+ * `AskTurn` has for the same reason. An adapter wires it in one line:
+ * `const c = new AbortController(); cancellation.onCancel(() => c.abort())`.
+ */
+interface Cancellation {
+  /** Called at most once: when the asker goes, or at once if it already has. */
+  onCancel(listener: () => void): void;
+}
+/**
+ * What one completion came to. Only the first is an answer.
+ *
+ * - `refused`: the provider declined in its response rather than in its text. `reason` is
+ *   for the person, and ends their run as a decline
+ *   ([0158](../../../docs/decisions/0158-a-model-may-decline.md)).
+ * - `truncated`: the answer reached the output limit. Cut off, it is not an answer, and
+ *   is never handed over as half a document.
+ * - `unavailable`: not reached, or it answered with an error. `status` is the provider's
+ *   HTTP status when it gave one; `cause` is for the operator's log, never the client.
+ * - `cancelled`: the asker went away and the request was abandoned.
+ */
+type Completion = {
+  readonly ok: true;
+  readonly text: string;
+} | {
+  readonly ok: false;
+  readonly failure: 'refused';
+  readonly reason: string;
+} | {
+  readonly ok: false;
+  readonly failure: 'truncated';
+} | {
+  readonly ok: false;
+  readonly failure: 'unavailable';
+  readonly status?: number;
+  readonly cause: string;
+} | {
+  readonly ok: false;
+  readonly failure: 'cancelled';
+};
+/**
+ * A model, asked to complete one prompt.
+ *
+ * A port because what is behind it is genuinely swappable: the deployment chooses Anthropic,
+ * OpenAI or xAI, `@formancy/server` has an adapter for each, and the tests drive the route
+ * through doubles. **It does not throw for a provider's failure**; it says which failure.
+ */
+interface Completer {
+  complete(prompt: CompletionPrompt, cancellation: Cancellation): Promise<Completion>;
+}
+/** A builder's request as the browser sends it, unread. */
+interface BuilderRequest {
+  readonly kind?: unknown;
+  readonly user?: unknown;
+}
+type BuilderRequestOutcome = Completion |
+/** Not one of the requests formancy makes, so there is no briefing to ask it under. */
+{
+  readonly ok: false;
+  readonly failure: 'unknown_kind';
+} |
+/** No text to ask about: the briefing alone, which no run sends. */
+{
+  readonly ok: false;
+  readonly failure: 'no_user';
+};
+/**
+ * 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.
+ */
+export declare function completeBuilderRequest(completer: Completer, request: BuilderRequest, cancellation: Cancellation): Promise<BuilderRequestOutcome>;
+//#endregion
+export { type Action, type Actor, type AttemptOutcome, type AuditAction, type AuditDraft, type AuditEntry, type AuthDeps, type AuthOutcome, type BreakerState, type BuilderRequest, type BuilderRequestOutcome, CHALLENGE_TTL_SECONDS, type Cancellation, type Challenge, type ClaimOutcome, type Completer, type Completion, type CompletionPrompt, DEFAULT_MAX_NUMBER, type DeliveryHeaders, type DeliveryRecord, type DraftMigration, type DraftRecord, type ExamplesOutcome, type ExamplesRecord, type FileRecord, type FormExamples, type FormRecord, type FormToFill, type FormVersionRecord, type KeepExamplesOutcome, type ListedForm, type ListedSubmission, type ListedVersion, type MembershipOutcome, type OfferDeps, type OfferInput, type OfferOutcome, type OutboxDeps, type PublishOutcome, type ReplayOutcome, type ResolvedForm, type ResumeOutcome, type Role, type ScanVerdict, type Scanner, type ScreenOutcome, type ServerDeps, type ServerOptionsSource, type ServerOptionsSources, type Solution, type Storage, type SubmissionOutcome, type SubmissionRecord, type UnsafePattern, type VerifyOutcome, type WebhookHealth, type WebhookRecord, decodeSolution, encodeSolution, hashOf, mintChallenge, solveChallenge, verifySolution };
 //# sourceMappingURL=index.d.mts.map