@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/forms.d.ts

@@ -0,0 +1,727 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The form entity: what a form IS, separately from the shape an author drew.
+ *
+ * `docs/specs/reusable-forms.md` §2. Before this module a form's whole
+ * identity was `formName` — the free-text caption an author typed into an
+ * inspector field, copied onto each submission at write time and reconciled
+ * with nothing. Renaming a form split its history; two pages sharing a label
+ * were one list. A document at `hosts/{hostId}/forms/{formId}` is the identity
+ * those surfaces were reading a caption in place of.
+ *
+ * Pure and dependency-free on purpose. This barrel reaches client bundles
+ * through `app-utils/index`, so nothing here may import a Node builtin — the
+ * constraint that holds `personKey` in its own module one directory over.
+ * Everything that needs Firestore or `node:crypto` lives at the call sites.
+ */
+import type { AglynNodeSchema, NodeId } from '../foundation/definitions/components.types';
+import type { PlacementKind } from './compose-reusable-components';
+/**
+ * The `componentId` of the node that RENDERS a form, and of the node that
+ * renders one of its fields.
+ *
+ * Persisted in screen, layout, component and form documents — never rename.
+ * Restated as constants because the walkers below, the promotion route and the
+ * graft all have to name the same two ids, and a copy that drifted would read
+ * as "this page has no form" rather than as an error.
+ */
+export declare const FORM_COMPONENT_ID = "form";
+export declare const FORM_FIELD_COMPONENT_ID = "formField";
+/**
+ * The prop on a `form` node naming the entity it is a placement OF.
+ *
+ * Persisted in screen documents — never rename.
+ */
+export declare const FORM_ID_PROP = "formId";
+/**
+ * What `/api/forms/submit` answers a submission to a site that switched Forms
+ * off (AGL-3029). A visitor reads it, so it names no plugin and no setting.
+ */
+export declare const FORMS_OFF_FOR_SITE_REFUSAL = "This site is not accepting form submissions";
+/**
+ * The plugin whose door a submission to `/api/forms/submit` came through
+ * (AGL-3029) — the plugin that must run on the site for it to be accepted.
+ *
+ * The endpoint is shared. A form element posts to it, and so does a Marketing
+ * popup's email capture, which is a Marketing element rather than a form: a
+ * site that switched Forms off and still shows its popup must not silently
+ * lose every address the popup collects. The popup names its door in the
+ * body; everything else is a form's.
+ *
+ * A body that names a form ENTITY or a dataset binding is a form's, whatever
+ * door it claims. Those are what a form element sends and a popup never does,
+ * so the popup door cannot be used to file rows under a form, or into a
+ * dataset, on a site that switched Forms off.
+ */
+export declare function formSubmissionDoorPlugin(body: Record<string, unknown> | null | undefined): string;
+/**
+ * How many forms one query for a site's catalog reads.
+ *
+ * ⛔ **NOT the allowance.** How many forms a site may hold is
+ * `PLAN_ENTITLEMENTS[plan].formsPerHost`, enforced at creation through
+ * `checkQuota` in `/api/hosts/resources`. A surface that shows a customer
+ * their ceiling MUST read that entitlement — this number is larger, so
+ * reading it instead overstates the cap on every plan.
+ *
+ * What this bounds is a READ. `hosts/{hostId}/forms` is small enough to list
+ * in one page, and the listing surfaces (the submissions filter, the entity
+ * picker) say so — but a bound below the allowance would make them silently
+ * drop forms the customer made and can see elsewhere, which is the invisible
+ * half of a wrong limit and the expensive one to discover.
+ *
+ * So it sits at or above every per-plan allowance, with headroom for the
+ * catalogs that legitimately exceed one: a per-org contract override, and any
+ * site that built past a ceiling before it was lowered. `forms.spec.ts` pins
+ * that relationship rather than trusting the two numbers to be moved
+ * together. A catalog past even this needs real pagination, not a larger
+ * constant.
+ */
+export declare const FORMS_MAX_PER_HOST = 1000;
+/** Field types a `FormField` node offers; the form declares the same set. */
+export type FormFieldType = 'text' | 'email' | 'textarea' | 'select' | 'radio' | 'checkbox' | 'rating';
+/**
+ * What a declared field MEANS, where the meaning is one the platform reads.
+ *
+ * The Inbox guesses today: `submission-presenter.ts` matches reduced field
+ * keys against a convention list, which is why a survey whose fields are
+ * `q1`…`q9` renders "Someone" on every row. A declared role is the author
+ * saying which field is the address instead of the platform inferring it from
+ * a name that was never a contract.
+ */
+export type FormFieldRole = 'name' | 'email' | 'phone' | 'consent';
+/** One field of a form, as the form declares it. */
+export interface FormFieldDecl {
+    /** THE submission key — matches the node's `fieldName` prop, not `label`. */
+    fieldName: string;
+    label?: string;
+    fieldType: FormFieldType;
+    required?: boolean;
+    options?: string[];
+    /** Stable dataset model fieldId this value is stored under (AGL-556). */
+    datasetFieldId?: string;
+    role?: FormFieldRole;
+    /**
+     * The custom contact field this value is saved under (AGL-2601) — a
+     * `ContactFieldDefinition.key` in the org that owns the site.
+     *
+     * Edited on the form's own page rather than drawn on the canvas, so it is
+     * NOT read off the nodes: `carryContactFieldMappings` carries it across a
+     * publish by `fieldName`, or a design change would silently unmap every
+     * field. The built-in properties — name, email, phone — are what `role`
+     * names; this is only ever a field the merchant defined.
+     */
+    contactFieldKey?: string;
+}
+/** Where a submission goes beyond the Inbox. */
+export interface FormRouting {
+    datasetId?: string;
+    /** Whether a submission carrying an address also becomes a lead. */
+    lead?: boolean;
+}
+/**
+ * What an adopted form claims of the history that predates it.
+ *
+ * Recorded at adoption from what was ACTUALLY written on the submissions —
+ * the caption and the page path — because those two fields are the whole of
+ * what a pre-entity submission carries. Read only by the backfill, and never
+ * by a live query: the live filter is an equality on `formId`.
+ */
+export interface FormLegacyMatch {
+    formName: string;
+    paths: string[];
+}
+/** The stored form document, minus the timestamps Firestore stamps. */
+export interface FormDocument<N = AglynNodeSchema> {
+    displayName: string;
+    slug: string;
+    fields: FormFieldDecl[];
+    /** Names the entry in `fields` that IS the marketing opt-in. */
+    consentFieldName?: string;
+    routing?: FormRouting;
+    legacyMatch?: FormLegacyMatch;
+    stats?: FormStats;
+    /**
+     * When this form was RETIRED, or absent while it is in use (AGL-2671).
+     *
+     * A retired form is kept, never deleted: its submissions, its leads and the
+     * contact timeline they built are the reason it still exists, and a form is
+     * the key those rows are filed under. What retirement changes is that it
+     * stops being a live lead surface — it leaves the forms list, it stops
+     * being graded by `/api/health/funnel`, and `/api/forms/submit` refuses it.
+     *
+     * `unknown` because the stored value is not one shape: the console writes a
+     * number, and a marker already in production is a Firestore `Timestamp`.
+     * {@link isFormArchived} is the only thing that should read it, and it asks
+     * about presence rather than about what kind of clock wrote it.
+     */
+    archivedAt?: unknown;
+    rootId?: NodeId;
+    nodes?: Record<NodeId, N>;
+    /**
+     * Which version is published.
+     *
+     * The same pointer `AglynHostComponent.versionId` is, including the rule
+     * that only a publisher may move it — the rules block denies an author the
+     * `versionId` key for components and this document is governed the same way.
+     */
+    versionId?: string;
+}
+/**
+ * Whether a form has been retired — see {@link FormDocument.archivedAt}.
+ *
+ * PRESENCE, not a number. Absent, `null` and `0` are "in use"; any other
+ * value is a retirement marker.
+ *
+ * ⛔ Deliberately NOT shaped like `isPipelineArchived`, which asks for a
+ * positive number. A pipeline stores its own numeric stamp; a form's is
+ * written by whatever retired it, and the marker already in production on at
+ * least one form is a Firestore `Timestamp` rather than a number. The two
+ * readers that predate this function — the list filter and
+ * `/api/health/funnel`'s probe — both test truthiness, so a stricter rule
+ * here does not tighten anything: it just disagrees with them, and the
+ * disagreement surfaces as a retired form reappearing in the catalog while
+ * the funnel goes on ignoring it.
+ *
+ * Measured, not assumed: with the numeric rule this function un-hid a form
+ * the probe was still skipping, and the two counts were 5 against 4.
+ *
+ * ⚠️ Asked of the STORED document. A caller that has already filtered a list
+ * must not re-derive this from a display flag; the field is the fact.
+ */
+export declare function isFormArchived(form: Pick<FormDocument, 'archivedAt'> | null | undefined): boolean;
+/**
+ * One entry in a form's `versions` subcollection.
+ *
+ * The draft the besigner writes on every save. `nodes` arrives compressed
+ * through the client converter, exactly as a component version's does, so
+ * this declares the decompressed shape the hook hands back.
+ */
+export interface FormVersion<N = AglynNodeSchema> {
+    formId: string;
+    hostId?: string;
+    displayName?: string;
+    rootId?: NodeId;
+    nodes?: Record<NodeId, N>;
+}
+/**
+ * Counters carried ON the form document, incremented on writes that were
+ * happening anyway.
+ *
+ * Never derived by counting `formSubmissions`. That collection grows without
+ * bound and is the one the customer is billed on; a console surface that
+ * counted it on render would be the expensive-read shape this product has
+ * created repeatedly. `hosts/{hostId}/overlays/{overlayId}.stats` is the same
+ * pattern with the same reasoning.
+ */
+export interface FormStats {
+    submissions?: number;
+    leads?: number;
+    lastSubmissionAtMs?: number;
+    /**
+     * Form views, counted by the beacon at `/api/analytics/collect` — one per
+     * rendered form on a live page, the same shape and the same cost as an
+     * overlay impression.
+     *
+     * ⚠️ A CLIENT-SIDE COUNT, and every rate over it inherits that. A blocked
+     * beacon, a browser that never runs the script and a crawler that renders
+     * nothing are all views this does not hold, while `submissions` is counted
+     * on the server and holds every one. So a completion rate over this can
+     * legitimately exceed 100%, and it is reported rather than clamped: a
+     * number capped at a round 100% looks like a measurement of a full house.
+     */
+    views?: number;
+    /** Forms a visitor typed into: one per form instance, on the first edit. */
+    starts?: number;
+    /**
+     * The same four counters, per calendar month.
+     *
+     * The series the detail surface draws, and — more importantly — what makes
+     * a rate over `views` honest. The lifetime totals cannot be divided into
+     * each other: `submissions` has counted since the form entity existed and
+     * `views` only since the beacon shipped, so a lifetime completion rate
+     * would divide a long history by a short one. {@link formStatsWindow} takes
+     * every rate over the months that carry BOTH counters.
+     *
+     * Bounded by the calendar: twelve keys a year on a document with a megabyte
+     * to spend. Keys are `submissionMonthKey()` — the SAME function the
+     * site-wide counter and the abuse ceiling are keyed by, imported rather
+     * than restated, because a differently-derived month key reads zero on
+     * exactly the months it disagrees about.
+     */
+    periods?: Record<string, FormPeriodStats>;
+}
+/** One month of {@link FormStats}. Every field absent until first written. */
+export interface FormPeriodStats {
+    submissions?: number;
+    leads?: number;
+    views?: number;
+    starts?: number;
+}
+/** The counters {@link FormPeriodStats} carries, in reading order. */
+export type FormStatKind = 'views' | 'starts' | 'submissions' | 'leads';
+export declare const FORM_STAT_KINDS: readonly FormStatKind[];
+/** One month of a form's history, with every counter resolved to a number. */
+export interface FormPeriodPoint extends Record<FormStatKind, number> {
+    /** `YYYY-MM`. */
+    period: string;
+}
+/**
+ * A form's history as a dense month series, from the first month anything was
+ * recorded to the last.
+ *
+ * ⛔ THE SERIES NEVER STARTS BEFORE THE COUNTER DID. A month with no key is
+ * two different facts — "nothing happened" and "nothing was counted yet" —
+ * and they are told apart by WHERE the month falls: inside the recorded range
+ * an absent key is a true zero, because the counter was live and wrote
+ * nothing; before it, there is no measurement to draw and the series simply
+ * does not extend there. Padding to a fixed twelve months would render the
+ * form's pre-counter history as a row of confident zeros.
+ *
+ * Interior gaps ARE filled, at zero, so a quiet month reads as a quiet month
+ * rather than closing up and making two distant months look adjacent.
+ *
+ * @param stats - the stored counters, or nothing.
+ * @param maxPeriods - how many of the most recent months to return.
+ * @returns oldest first, so a chart reads left to right. Empty when nothing
+ *          has ever been recorded.
+ */
+export declare function formPeriodSeries(stats: FormStats | undefined | null, maxPeriods?: number): FormPeriodPoint[];
+/** Two counters summed over the months where the FIRST of them was recorded. */
+export interface FormStatsWindow {
+    /** Months the window covers. Zero means no rate can be taken. */
+    periods: number;
+    /** The counter the window is defined by, summed over those months. */
+    over: number;
+    /** The other counter, summed over the SAME months. */
+    of: number;
+}
+/**
+ * Sum `of` and `over` across exactly the months in which `over` was recorded.
+ *
+ * This is what stops a rate being a lie of arithmetic. `views` began being
+ * counted the day the beacon shipped and `submissions` has counted since the
+ * form entity existed, so dividing the lifetime totals answers "submissions
+ * ever, over views since Tuesday" — a number that is not wrong by a little.
+ *
+ * A month is IN the window when it carries a non-zero `over`, not merely a
+ * key: a month the beacon never reported is not a month with no views, it is
+ * a month with no measurement, and including it would deflate every rate
+ * taken over the window by however long the counter was dark.
+ *
+ * @returns `periods: 0` when nothing qualifies, which every caller must
+ *          render as a dash rather than as a zero rate.
+ */
+export declare function formStatsWindow(stats: FormStats | undefined | null, over: FormStatKind, of: FormStatKind): FormStatsWindow;
+/**
+ * A span of calendar months, both ends inclusive, keyed as `YYYY-MM`.
+ *
+ * An absent end is OPEN rather than zero: a span that starts in March and
+ * never closes covers every month from March onward. A span with neither end
+ * is not a span, and {@link formStatsTotals} answers it with lifetime totals.
+ */
+export interface FormPeriodRange {
+    from?: string | null;
+    to?: string | null;
+}
+/**
+ * The month key a moment falls in, or `null` for a moment that is not one.
+ *
+ * UTC, through {@link submissionMonthKey}, because that is the function every
+ * writer of `stats.periods` keys by. A month derived any other way reads zero
+ * on exactly the months the two definitions disagree about — which is the
+ * boundary month, the one a reader is most likely to be asking about.
+ */
+export declare function formPeriodKey(atMs: number | null | undefined): string | null;
+/**
+ * A form's four counters, summed, with what the sum covers.
+ *
+ * Every counter is `number | null` and the distinction is load-bearing. A
+ * counter is `null` when nothing was recorded for it at all: `leads` is
+ * incremented only by a form whose `routing.lead` is set, so a form that does
+ * not route leads has no leads measurement rather than a measured zero, and a
+ * `0` in that slot states a result nobody took.
+ */
+export interface FormStatsTotals {
+    views: number | null;
+    starts: number | null;
+    submissions: number | null;
+    leads: number | null;
+    /**
+     * Month keys that contributed. `null` when the totals are lifetime, which
+     * is what tells a caller whether the figures are confined to a span.
+     */
+    periods: number | null;
+}
+/**
+ * Sum a form's counters — over its whole history, or over a span of months.
+ *
+ * ## Lifetime and windowed are different questions, and the caller picks
+ *
+ * The flat counters on {@link FormStats} have counted since the form entity
+ * existed. Passing no range returns those, and `periods: null` says so, so a
+ * surface can label the figure lifetime instead of implying it belongs to
+ * whatever the surface is about.
+ *
+ * Passing a range sums `stats.periods` instead, over exactly the month keys
+ * inside it. The two can differ by a lot in both directions: the month series
+ * began later than the flat counters, so a windowed total over a form's whole
+ * history can still be smaller than its lifetime total.
+ *
+ * ## What `null` means here, and why an in-range zero is not it
+ *
+ * A counter stays `null` unless some in-range month actually carries it. This
+ * is the same rule {@link formStatsWindow} applies to a rate's denominator,
+ * and it exists for the same reason: a month that carries `submissions` and
+ * no `leads` key is not a month with zero leads, it is a month in which
+ * nothing counted leads.
+ *
+ * ## Whole months, and a range boundary that lands inside one
+ *
+ * `stats.periods` is keyed by calendar month, so the finest a windowed total
+ * can be is a month. A range that starts on the 20th takes that whole month,
+ * including the days before it. A caller reporting a windowed figure has to
+ * say the window is measured in whole months; nothing here can narrow it.
+ *
+ * @param stats - the stored counters, or nothing.
+ * @param range - the months to confine the sum to. Omitted, or with neither
+ *                end, gives lifetime totals.
+ */
+export declare function formStatsTotals(stats: FormStats | undefined | null, range?: FormPeriodRange | null): FormStatsTotals;
+export declare const FORM_SLUG_MAX_LENGTH = 64;
+export declare const FORM_DISPLAY_NAME_MAX_LENGTH = 100;
+/**
+ * A stable, url-safe handle for a form, derived from its display name.
+ *
+ * The slug is NOT the identity — `formId` is, and the slug is free to be
+ * regenerated. It exists so a console URL and an export filename can name a
+ * form in something a human recognizes without either becoming a second
+ * identity the way `formName` did.
+ *
+ * @returns the slug, or `''` when the input reduces to nothing — a caller
+ *          must fall back to the document id rather than store an empty slug.
+ */
+export declare function normalizeFormSlug(input: unknown): string;
+/**
+ * Every `formField` descendant of `formNodeId`, in the order the author
+ * placed them.
+ *
+ * Depth-first pre-order, because that IS the reading order of the rendered
+ * form and the order a per-form submission list wants its columns in. A
+ * breadth-first walk would interleave the fields of two adjacent groups.
+ *
+ * Nesting between the form and its fields is arbitrary — the `Form` runtime
+ * makes a point of riding the DOM precisely so it needs no React context — so
+ * the walk cannot assume fields are direct children.
+ *
+ * Repeated and unknown ids are skipped, which bounds a cyclic document.
+ */
+export declare function collectFormFieldNodeIds(nodes: Record<NodeId, AglynNodeSchema | undefined> | undefined | null, formNodeId: NodeId, formFieldComponentId?: string): NodeId[];
+/**
+ * Reads a form's declared field list off the nodes an author already drew.
+ *
+ * This is the whole of what adoption has to invent, and it invents nothing:
+ * `fieldName`, `fieldType`, `label`, `required`, `options` and
+ * `datasetFieldId` are all already props on the `formField` nodes. A form
+ * adopted from a page therefore declares exactly the form that page was
+ * already submitting.
+ *
+ * A field with no `fieldName` is DROPPED rather than defaulted. The runtime
+ * falls back to `name = fieldName || 'field'`, so several unnamed fields
+ * collapse onto one submission key — declaring them would put a key in the
+ * schema that does not identify a value.
+ *
+ * A duplicate `fieldName` keeps its FIRST occurrence, matching the submission
+ * the runtime produces: `FormData` entries under one key are joined into that
+ * one key, so the second node contributes no separate value.
+ */
+export declare function formFieldDeclsFromNodes(nodes: Record<NodeId, AglynNodeSchema | undefined> | undefined | null, formNodeId: NodeId, formFieldComponentId?: string): FormFieldDecl[];
+/** One `form` node found by the discovery scan, with where it was found. */
+export interface DiscoveredFormNode {
+    /** `screen` / `layout` / `component` — what kind of document holds it. */
+    sourceKind: 'screen' | 'layout' | 'component';
+    sourceId: string;
+    sourceName?: string;
+    nodeId: NodeId;
+    /** The caption the node carries today, normalized the way the route is. */
+    formName: string;
+    /** Already bound, when the node carries a `formId`. */
+    formId?: string;
+    fields: FormFieldDecl[];
+}
+/**
+ * Finds every `form` node in one document's node map.
+ *
+ * The corpus and the shape are the *Used by* scan's: a flat
+ * `Record<NodeId, AglynNodeSchema>` per screen, layout and component
+ * definition. That scan is idle until asked, for the reason its card states
+ * in full — reading every screen and every layout on mount is the
+ * expensive-read shape this codebase has a standing rule against — and this
+ * one inherits that posture rather than re-arguing it.
+ */
+export declare function discoverFormNodes(nodes: Record<NodeId, AglynNodeSchema | undefined> | undefined | null, source: {
+    kind: DiscoveredFormNode['sourceKind'];
+    id: string;
+    name?: string;
+}, ids?: {
+    form?: string;
+    formField?: string;
+}): DiscoveredFormNode[];
+/**
+ * A form entity's published design, in the shape the graft consumes: the
+ * `rootId`/`nodes` snapshot that lives on `hosts/{hostId}/forms/{formId}`.
+ *
+ * Structurally a component definition minus the parts a form does not have —
+ * no declared props, no icon — which is why the graft can take both. It is
+ * `Pick`ed off {@link FormDocument} rather than restated so the storage
+ * contract stays the single description of what is written there.
+ */
+export type PlacedFormDesign<N = AglynNodeSchema> = Required<Pick<FormDocument<N>, 'rootId' | 'nodes'>>;
+/**
+ * Whether any node in this map PLACES a form entity (as opposed to merely
+ * drawing an unbound form inline).
+ *
+ * The cost gate in front of the forms read, and cheap on purpose: one scan of
+ * a map the caller already holds, against a read that is a whole collection
+ * query. Most pages carry no form at all, and a page whose form nodes are all
+ * unbound has nothing an entity could contribute — either way there is nothing
+ * for the graft to resolve, so the query buys nothing.
+ *
+ * Says nothing about whether the named form EXISTS or is published; that is
+ * settled by the graft, against documents this cannot see.
+ */
+export declare function placesFormEntity(nodes: Record<NodeId, AglynNodeSchema | undefined> | undefined | null): boolean;
+/**
+ * Whether any node in this map places THIS form.
+ *
+ * The per-id half of {@link placesFormEntity}, and the predicate a usage scan
+ * asks of a screen, a layout or a component definition. Deliberately the same
+ * reader the graft resolves against: a scan that disagreed about what counts
+ * as a placement would drop the caches of the wrong pages, and the pages it
+ * missed would serve the old form for the whole revalidate window with nothing
+ * recording that they were skipped.
+ */
+export declare function nodesPlaceForm(nodes: Record<NodeId, AglynNodeSchema | undefined> | undefined | null, formId: string): boolean;
+/**
+ * The `form` node inside a form's OWN design.
+ *
+ * A form document's tree holds exactly one, because the document IS that
+ * form — but the tree is a flat map under a synthetic canvas root, so the
+ * node has to be found rather than assumed to be the root itself.
+ *
+ * Here rather than at each surface because every reader of a form's design
+ * needs it before it can ask anything else: the form's page to run
+ * `checkFormContract`, the promotion route to publish, the preview to draw,
+ * {@link formDesignReboundTo} to rewrite the binding. A caller that found
+ * the node its own way and one that found it this way must agree, or a
+ * design reads as "no form here" on one surface and as bound on the next.
+ */
+export declare function formNodeIdIn(nodes: Record<NodeId, AglynNodeSchema | undefined> | undefined | null): NodeId | undefined;
+/**
+ * The same design, naming `identity` instead of whichever form it named
+ * before — or `null` when it already did.
+ *
+ * ## Why a copied design must be rewritten rather than carried
+ *
+ * A form's design names its own form in a prop (AGL-3024). That binding is
+ * what `/api/forms/submit` stamps a submission with and what the form's own
+ * submission list is an equality on, so a design that travels to a SECOND
+ * form — duplicated, imported, installed from a starter — arrives naming the
+ * first one, and every submission the second form collects is filed under the
+ * first. Nothing about that is visible: the copy renders, the visitor
+ * submits, the row lands, and the copy's own list simply never grows.
+ * `checkFormContract` calls it `form-id-unbound`, and it is the one violation
+ * a copy CAUSES rather than inherits.
+ *
+ * So every path that gives a stored design to a different form rebinds it
+ * here, with the same two props the Forms page's Create stamps on a new one:
+ * the id the submissions are keyed on, and the caption they are labelled
+ * with in the Inbox. Leaving the caption behind is the quieter half of the
+ * same bug — the copy's submissions arrive titled with the source's name.
+ *
+ * `null` for "nothing to write", so a caller holding a compressed tree can
+ * skip the decode-rewrite-encode round trip entirely in the common case.
+ * A design with no form node in it returns `null` too: there is no binding
+ * to move, and inventing one is not this function's decision.
+ *
+ * Pure — the input map and its nodes are not changed.
+ */
+export declare function formDesignReboundTo<N extends AglynNodeSchema = AglynNodeSchema>(nodes: Record<NodeId, N> | undefined | null, identity: {
+    formId: string;
+    formName?: string | null;
+}): Record<NodeId, N> | null;
+/**
+ * The placement kind that makes a placed form render its ENTITY'S design.
+ *
+ * Until this existed the entity's tree was written on every publish and read
+ * by nothing: a form's fields had to be redrawn on each page that placed it,
+ * and editing the form propagated nowhere. The two documents disagreed the
+ * moment either changed, and the page always won.
+ *
+ * `replacesAuthoredChildren` is what makes that propagation real, and it is
+ * the reason the resolution rule is strict. The rule, stated once:
+ *
+ * - Entity has a published design → the entity's fields ARE the form. Whatever
+ *   the page drew inside the form node is discarded, exactly as a reusable
+ *   instance's child list is replaced by its definition's. This is what "edit
+ *   the form once" means; a merge would render a page's stale copy of a field
+ *   beside the entity's current one.
+ * - Entity has no published design, is archived away, or the `formId` names
+ *   nothing → the form node is left completely alone, inline fields included.
+ *   Every form built before the entity existed is in this state, so this is
+ *   the branch that keeps the live site rendering exactly what it renders
+ *   today.
+ *
+ * A deleted or unpublished entity therefore degrades to the page's own copy
+ * rather than to an empty form — the same fail-open posture the component
+ * graft takes for an unresolvable `refId`, and for the same reason: a
+ * document going missing must not take a published page's content with it.
+ *
+ * The discard is a COMPOSE-time one, so it takes nothing away permanently:
+ * the page's fields stay in its document, and clearing the binding brings
+ * them straight back. That is what makes binding an existing hand-built form
+ * to an entity a reversible act rather than a destructive one.
+ */
+export declare function placedFormPlacement<N extends AglynNodeSchema = AglynNodeSchema>(formsById: Record<string, PlacedFormDesign<N> | undefined> | undefined): PlacementKind<N>;
+/**
+ * The caption as the submit route stores it.
+ *
+ * Restated here so discovery and the backfill compare the same string the
+ * route wrote: `String(formName ?? 'Form').slice(0, 100)`. A differently
+ * derived caption on either side would make every legacy match miss, silently
+ * and in the safe direction — which is the failure that looks like success.
+ */
+export declare function normalizeSubmissionFormName(value: unknown): string;
+/** The page path as the submit route stores it. */
+export declare function normalizeSubmissionPath(value: unknown): string;
+/** A form as the backfill sees it: an id and what it claims of the past. */
+export interface LegacyMatchCandidate {
+    formId: string;
+    legacyMatch?: FormLegacyMatch | null;
+}
+/**
+ * Which adopted form, if any, a pre-entity submission belongs to.
+ *
+ * ⛔ **An ambiguous submission is left UNSTAMPED, always.** The two failure
+ * modes are not symmetric and the asymmetry is the whole rule:
+ *
+ *  - An unmatched row is still in the Inbox, still readable, still exportable
+ *    over `/v1`. It is missing from ONE form's list, the Forms page says how
+ *    many rows are in that state, and a later adoption can still claim it.
+ *  - A wrongly stamped row is filed under a form it was never sent to. It
+ *    leaves the Inbox's *Unassigned* view, joins a stranger's submission list,
+ *    and nothing on any screen says it moved. It is invisible, and invisible
+ *    is not recoverable.
+ *
+ * So the match is on the PAIR. `formName` alone is a caption two pages may
+ * legitimately share — that shared caption is the defect the form entity
+ * exists to fix, and using it as the migration key would carry the defect into
+ * the migration. `path` is what tells two same-named forms apart, and it only
+ * does so when it was distinct, so both must agree and exactly one form may
+ * claim the pair.
+ *
+ * @returns the form id to stamp, or `null` to leave the row alone. Never a
+ *          best guess.
+ */
+export declare function matchSubmissionToForm(submission: {
+    formName?: unknown;
+    path?: unknown;
+}, candidates: readonly LegacyMatchCandidate[]): string | null;
+/**
+ * The value of the declared consent field, as a marketing opt-in.
+ *
+ * ⛔ THE FACT OF SUBMISSION IS NOT AN OPT-IN, and a form that declares no
+ * consent field produces no consent record — on any plan, at any time. This
+ * reads ONE field, named by the form's own `consentFieldName`, and asks
+ * whether the visitor ticked it.
+ *
+ * That is not in tension with the standing rule that consent is never
+ * inferred: a checkbox the visitor ticked IS an explicit checkbox. What the
+ * entity adds is a declared place to look, in place of the closed name list
+ * the route has to fall back on when no form is bound.
+ *
+ * What counts as the tick is {@link isConsentCheckboxTicked}'s, asked with
+ * the consent field's own declaration from `form.fields`.
+ *
+ * Returns `false`, never `undefined`: every writer downstream stores consent
+ * absent-or-true and must never write `false` over an opt-in captured
+ * elsewhere.
+ */
+export declare function readFormDeclaredConsent(form: {
+    consentFieldName?: string;
+    /** The STORED declaration, for the consent field's type and options. */
+    fields?: ReadonlyArray<Pick<FormFieldDecl, 'fieldName' | 'fieldType' | 'options'>> | null;
+} | null | undefined, fields: Record<string, unknown> | null | undefined): boolean;
+/**
+ * Whether a posted value ticks a consent checkbox.
+ *
+ * A tick arrives in one of two shapes. A box with no text of its own posts
+ * one of {@link AFFIRMATIVE_CHECKBOX_VALUES}. A Checkboxes field posts the
+ * TEXT of the option that was ticked — which is what lets its option say what
+ * the person agrees to — so when the field's declaration is a checkbox with
+ * exactly one option, that option's text, alone, is a tick too: compared as
+ * the renderer draws it, trimmed, or as a list holding only it. A field with
+ * several options is a question with several answers, and none of them is
+ * the opt-in by its text.
+ *
+ * ⛔ The declaration must come from the STORED form document, never from the
+ * request: a declaration a caller could send would let any submission name
+ * its own words as the opt-in.
+ */
+export declare function isConsentCheckboxTicked(value: unknown, declaration?: Pick<FormFieldDecl, 'fieldType' | 'options'> | null): boolean;
+/** Checkbox values a browser form actually posts for a ticked box. */
+export declare const AFFIRMATIVE_CHECKBOX_VALUES: Set<string>;
+/**
+ * The field names the submit route reads an opt-in from when the form
+ * declares no consent field.
+ *
+ * A CLOSED list rather than a substring match on "consent": a merchant's
+ * field called `consentToTreatment` on a clinic intake form is a different
+ * instrument entirely, and matching it would manufacture a marketing basis
+ * out of a medical one. Compared after {@link isMarketingConsentFieldName}'s
+ * normalization, so `Subscribe to newsletter` and `subscribeToNewsletter`
+ * are one name.
+ */
+export declare const MARKETING_CONSENT_FIELD_NAMES: ReadonlySet<string>;
+/**
+ * Whether a field, by its name alone, is one the submit route reads an
+ * opt-in out of when no consent field is declared.
+ *
+ * Asked of a DESIGN by the publish check and of a PAYLOAD by the route, so
+ * the two cannot disagree about which undeclared field counts as consent.
+ */
+export declare function isMarketingConsentFieldName(name: unknown): boolean;
+/**
+ * The marketing consent field: the props the Forms editor's **Marketing
+ * consent** preset places on a Form Field, and the ones a form generated from
+ * a brief carries.
+ *
+ * A Checkboxes field with ONE option, unticked and not required. The option
+ * says what the person agrees to, because a Checkboxes field posts the text
+ * of the option that was ticked and {@link isConsentCheckboxTicked} reads that
+ * text as the tick. So the option holds no comma and no line break: the
+ * Options setting starts a new box at each, and a second box is an answer
+ * that is not the opt-in. A site owner may reword the label and the option;
+ * the form names the field as its `consentFieldName` for a tick to count.
+ */
+export declare const MARKETING_CONSENT_FORM_FIELD: Readonly<{
+    fieldName: string;
+    label: string;
+    fieldType: FormFieldType;
+    options: string;
+    required: boolean;
+}>;