@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/foreign-script.js

@@ -0,0 +1,102 @@
+/**
+ * @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.
+ */ /**
+ * Code running in our pages that no deployment of ours served (AGL-2786).
+ *
+ * Two collectors have to tell our code from somebody else's running inside
+ * the same document, and both answer it from a URL: the CSP collector off a
+ * violation's source or blocked URI, the error beacon off every frame of a
+ * stack. They read ONE list, because a second copy fails silently — a scheme
+ * learned in one place goes on paging from the other.
+ *
+ * Pure and framework-free: the beacon ships in every page's client bundle and
+ * the ingestion routes run the same rule on the server, so nothing here may
+ * reach `window` or a Node builtin.
+ */ /**
+ * Schemes no deployment of ours serves a script from.
+ *
+ * - Extension content scripts, the overwhelming majority of CSP reports on
+ *   any real deployment: `chrome-extension:`, `moz-extension:`,
+ *   `safari-extension:`, `safari-web-extension:`, `edge-extension:`.
+ * - `webkit-masked-url:` — Safari's redaction of the same thing. Opaque, so
+ *   it can never be actioned, and it arrives in volume.
+ * - `chrome:`, `resource:`, `asset:` — the browser's and the embedding app's
+ *   own internals.
+ * - `iabjs:` — the scheme Meta's Facebook/Instagram Android in-app browser
+ *   evaluates its own scripts under. Measured 2026-09-10 in `client-errors`:
+ *   `Error invoking postMessage: Java object is gone`, every frame under
+ *   `iabjs://navigation_performance_logger_android`, thrown by the webview's
+ *   native bridge as the page unloaded.
+ *
+ * Schemes, not vendors or function names: a new webview adds a scheme at
+ * most, and nothing on this list can ever be ours.
+ */ export const FOREIGN_SCRIPT_SCHEMES = [
+    'chrome-extension:',
+    'moz-extension:',
+    'safari-extension:',
+    'safari-web-extension:',
+    'edge-extension:',
+    'webkit-masked-url:',
+    'chrome:',
+    'resource:',
+    'asset:',
+    'iabjs:'
+];
+/** Is this URL under a scheme no deployment of ours serves? */ export function isForeignScriptUrl(value) {
+    const lowered = value.toLowerCase();
+    return FOREIGN_SCRIPT_SCHEMES.some((scheme)=>lowered.startsWith(scheme));
+}
+/**
+ * Every URL a stack frame points at, whichever engine produced the stack.
+ *
+ * One pattern covers both formats because the frame's URL is always followed
+ * by `:line:col`: V8 writes `at fn (URL:1:2)` and `at URL:1:2`, WebKit and
+ * Firefox write `fn@URL:1:2` and `@URL:1:2`. Matching on the suffix rather
+ * than on the prefix means neither engine needs its own branch, and a format
+ * this code has never seen degrades to "no frames parsed" rather than to a
+ * wrong answer.
+ *
+ * ANY scheme, not a list of web ones. A frame the pattern cannot read does
+ * not parse, and a stack made only of such frames reads as "no frames" —
+ * which every caller treats as no evidence and keeps. That is how an
+ * `iabjs://` stack came to be reported as ours.
+ */ export function stackFrameUrls(stack) {
+    const urls = [];
+    const frame = /([a-z][a-z0-9+.-]*:\/\/[^\s()]+?):\d+:\d+/gi;
+    let match;
+    while((match = frame.exec(stack)) !== null)urls.push(match[1]);
+    return urls;
+}
+/**
+ * Was every frame of this stack evaluated under a foreign scheme?
+ *
+ * ⚑ `every`, never `some`: injected code calling into ours is OUR bug the
+ * moment one of our frames is on the stack, so a single first-party frame —
+ * a served chunk, a CDN asset, the document itself — keeps the report.
+ *
+ * No frames parsed is not evidence of anything, so it is false.
+ *
+ * The document is NOT foreign here. The beacon also drops a stack whose
+ * frames are the document (see `isInjectedThirdPartyFrame`), but only for an
+ * uncaught error, in the browser, against the page's own URL. Anything
+ * reading a stack without that context must not guess.
+ */ export function isForeignScriptStack(stack) {
+    const urls = stackFrameUrls(stack);
+    if (!urls.length) return false;
+    return urls.every((url)=>isForeignScriptUrl(url));
+}
+
+//# sourceMappingURL=foreign-script.js.map

package/src/lib/app-utils/foreign-script.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/foreign-script.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Code running in our pages that no deployment of ours served (AGL-2786).\n *\n * Two collectors have to tell our code from somebody else's running inside\n * the same document, and both answer it from a URL: the CSP collector off a\n * violation's source or blocked URI, the error beacon off every frame of a\n * stack. They read ONE list, because a second copy fails silently — a scheme\n * learned in one place goes on paging from the other.\n *\n * Pure and framework-free: the beacon ships in every page's client bundle and\n * the ingestion routes run the same rule on the server, so nothing here may\n * reach `window` or a Node builtin.\n */\n\n/**\n * Schemes no deployment of ours serves a script from.\n *\n * - Extension content scripts, the overwhelming majority of CSP reports on\n *   any real deployment: `chrome-extension:`, `moz-extension:`,\n *   `safari-extension:`, `safari-web-extension:`, `edge-extension:`.\n * - `webkit-masked-url:` — Safari's redaction of the same thing. Opaque, so\n *   it can never be actioned, and it arrives in volume.\n * - `chrome:`, `resource:`, `asset:` — the browser's and the embedding app's\n *   own internals.\n * - `iabjs:` — the scheme Meta's Facebook/Instagram Android in-app browser\n *   evaluates its own scripts under. Measured 2026-09-10 in `client-errors`:\n *   `Error invoking postMessage: Java object is gone`, every frame under\n *   `iabjs://navigation_performance_logger_android`, thrown by the webview's\n *   native bridge as the page unloaded.\n *\n * Schemes, not vendors or function names: a new webview adds a scheme at\n * most, and nothing on this list can ever be ours.\n */\nexport const FOREIGN_SCRIPT_SCHEMES: readonly string[] = [\n  'chrome-extension:',\n  'moz-extension:',\n  'safari-extension:',\n  'safari-web-extension:',\n  'edge-extension:',\n  'webkit-masked-url:',\n  'chrome:',\n  'resource:',\n  'asset:',\n  'iabjs:',\n]\n\n/** Is this URL under a scheme no deployment of ours serves? */\nexport function isForeignScriptUrl(value: string): boolean {\n  const lowered = value.toLowerCase()\n  return FOREIGN_SCRIPT_SCHEMES.some((scheme) => lowered.startsWith(scheme))\n}\n\n/**\n * Every URL a stack frame points at, whichever engine produced the stack.\n *\n * One pattern covers both formats because the frame's URL is always followed\n * by `:line:col`: V8 writes `at fn (URL:1:2)` and `at URL:1:2`, WebKit and\n * Firefox write `fn@URL:1:2` and `@URL:1:2`. Matching on the suffix rather\n * than on the prefix means neither engine needs its own branch, and a format\n * this code has never seen degrades to \"no frames parsed\" rather than to a\n * wrong answer.\n *\n * ANY scheme, not a list of web ones. A frame the pattern cannot read does\n * not parse, and a stack made only of such frames reads as \"no frames\" —\n * which every caller treats as no evidence and keeps. That is how an\n * `iabjs://` stack came to be reported as ours.\n */\nexport function stackFrameUrls(stack: string): string[] {\n  const urls: string[] = []\n  const frame = /([a-z][a-z0-9+.-]*:\\/\\/[^\\s()]+?):\\d+:\\d+/gi\n  let match: RegExpExecArray | null\n  while ((match = frame.exec(stack)) !== null) urls.push(match[1])\n  return urls\n}\n\n/**\n * Was every frame of this stack evaluated under a foreign scheme?\n *\n * ⚑ `every`, never `some`: injected code calling into ours is OUR bug the\n * moment one of our frames is on the stack, so a single first-party frame —\n * a served chunk, a CDN asset, the document itself — keeps the report.\n *\n * No frames parsed is not evidence of anything, so it is false.\n *\n * The document is NOT foreign here. The beacon also drops a stack whose\n * frames are the document (see `isInjectedThirdPartyFrame`), but only for an\n * uncaught error, in the browser, against the page's own URL. Anything\n * reading a stack without that context must not guess.\n */\nexport function isForeignScriptStack(stack: string): boolean {\n  const urls = stackFrameUrls(stack)\n  if (!urls.length) return false\n  return urls.every((url) => isForeignScriptUrl(url))\n}\n"],"names":["FOREIGN_SCRIPT_SCHEMES","isForeignScriptUrl","value","lowered","toLowerCase","some","scheme","startsWith","stackFrameUrls","stack","urls","frame","match","exec","push","isForeignScriptStack","length","every","url"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;CAYC,GAED;;;;;;;;;;;;;;;;;;CAkBC,GACD,OAAO,MAAMA,yBAA4C;IACvD;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;CACD,CAAA;AAED,6DAA6D,GAC7D,OAAO,SAASC,mBAAmBC,KAAa;IAC9C,MAAMC,UAAUD,MAAME,WAAW;IACjC,OAAOJ,uBAAuBK,IAAI,CAAC,CAACC,SAAWH,QAAQI,UAAU,CAACD;AACpE;AAEA;;;;;;;;;;;;;;CAcC,GACD,OAAO,SAASE,eAAeC,KAAa;IAC1C,MAAMC,OAAiB,EAAE;IACzB,MAAMC,QAAQ;IACd,IAAIC;IACJ,MAAO,AAACA,CAAAA,QAAQD,MAAME,IAAI,CAACJ,MAAK,MAAO,KAAMC,KAAKI,IAAI,CAACF,KAAK,CAAC,EAAE;IAC/D,OAAOF;AACT;AAEA;;;;;;;;;;;;;CAaC,GACD,OAAO,SAASK,qBAAqBN,KAAa;IAChD,MAAMC,OAAOF,eAAeC;IAC5B,IAAI,CAACC,KAAKM,MAAM,EAAE,OAAO;IACzB,OAAON,KAAKO,KAAK,CAAC,CAACC,MAAQjB,mBAAmBiB;AAChD"}

package/src/lib/app-utils/form-abuse-ceiling.d.ts

@@ -0,0 +1,146 @@
+/**
+ * @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 two audiences of a tripped form-submission abuse ceiling (AGL-1666).
+ *
+ * AGL-1655 made the ceiling refuse correctly and bill nothing, but it refused
+ * into silence: the visitor got the component's generic "something went
+ * wrong" and the site's owner got a Firestore document. This module holds the
+ * words both of them see, in one place, because the two are constrained in
+ * OPPOSITE directions and a single file is the only way to keep that visible:
+ *
+ *  - The **visitor** is a stranger to the site. They must be told plainly
+ *    that their message did not arrive, and must NOT be told why — that this
+ *    site passed an abuse threshold is the owner's business, not a caller's.
+ *  - The **owner** needs exactly the withheld half: the count, the ceiling,
+ *    and when it lifts.
+ */
+/**
+ * Refusal code carried by the abuse-ceiling 429 (AGL-1655).
+ *
+ * The Free plan's monthly wall answers 429 too, so the STATUS identifies
+ * nothing — this code is the whole discriminator, and one means "the customer
+ * needs a bigger plan" while the other means "this site is being flooded".
+ * Shared rather than restated so the producer and the consumer cannot drift.
+ */
+export declare const FORM_ABUSE_CEILING_CODE = "form-abuse-ceiling";
+/**
+ * The month key both the billable counter and the refusal counter are keyed
+ * by. UTC, matching the month boundary the ceiling resets on.
+ */
+export declare function submissionMonthKey(now?: Date): string;
+/** What the visitor is shown when a site's form is not accepting. */
+export interface FormUnavailableNotice {
+    /** The whole message. Fixed copy — never the server's terse `error`. */
+    message: string;
+    /**
+     * An alternative way to reach the site, when the site publishes one
+     * (`business.supportEmail`, the token whose own description is "where
+     * visitors should write for help"). Absent when it does not.
+     */
+    contact?: string;
+}
+/**
+ * The visitor's sentence.
+ *
+ * Three things it must not do, all of which the generic error branch did or
+ * a friendlier rewrite would:
+ *
+ *  1. **Not blame the visitor.** They filled in a form correctly. Nothing
+ *     about their message, their address or their retry is the reason.
+ *  2. **Not explain.** "Unusual volume", "temporarily over its limit", even
+ *     "this site is receiving too many messages" all tell a stranger
+ *     something about the site owner's account that the owner never chose to
+ *     publish. The refusal is the owner's problem to see, not the caller's.
+ *  3. **Not sound delivered.** "We'll get back to you", or anything ending
+ *     in a thank-you, converts a lost lead into a person waiting for a reply
+ *     that is never coming. So it says, in as many words, that the message
+ *     was not sent.
+ *
+ * What is left is short on purpose. The one genuinely useful thing to add is
+ * a door that still opens, which is why `contact` rides along.
+ */
+export declare const FORM_UNAVAILABLE_MESSAGE: string;
+/**
+ * Does this refused submit mean "this site's form is not accepting", rather
+ * than "something broke"?
+ *
+ * Takes the BODY only, deliberately. The obvious signature — `(status, body)`,
+ * matching `parseLockdownRefusal` — invites a caller to gate on the status
+ * first, and the status is precisely what does not distinguish this refusal
+ * from the Free plan's monthly wall. A caller holding only this function
+ * cannot make that mistake.
+ *
+ * Returns `null` for every other body, so a caller's existing generic error
+ * branch keeps handling real failures. Dressing a 500 as a deliberate pause
+ * would be the same class of lie in the other direction.
+ */
+export declare function parseFormUnavailableRefusal(body: unknown): FormUnavailableNotice | null;
+/** What the site's owner is shown while their form is paused. */
+export interface FormsPausedOwnerNotice {
+    title: string;
+    /** What happened, how many, and that none of it is billed. */
+    message: string;
+    /** When it lifts, as a local-reading sentence — never a raw month key. */
+    until: string;
+}
+/**
+ * The moment the ceiling resets: 00:00 UTC on the first of next month, which
+ * is the same boundary AGL-1655's `Retry-After` points at and the same one
+ * the `YYYY-MM` counter key rolls over on.
+ */
+export declare function formCeilingResetAt(now?: Date): Date;
+/**
+ * The honeypot's month, as the one sentence every surface renders (AGL-1831
+ * staff chip tooltip, AGL-1836 owner inbox notice).
+ *
+ * The framing is the point, and it is why the sentence lives here instead of
+ * in either component: the count reports the honeypot WORKING — caught and
+ * dropped, nothing stored, nothing billed — not something wrong. A surface
+ * that restated it could drift into alarm ("N spam attacks!") and train the
+ * owner to fear the number that should reassure them. It is also the
+ * AGL-1664 revisit input: spam creeping toward ~20% of a paying host's
+ * submissions is the trigger for reopening the App Check / CAPTCHA call.
+ *
+ * Returns `null` below one catch, same rule as `formSubmissionsPausedNotice`
+ * and for the same reason — the counter document persists from its first
+ * catch forever, and a reassuring zero trains the reader to ignore the row.
+ */
+export declare function formSpamCaughtNotice(input: {
+    spam: number;
+}): string | null;
+/**
+ * The owner's notice — the half deliberately withheld from the visitor.
+ *
+ * Shaped like `LockdownRefusalNotice` ({title, message, until}) so the
+ * console renders it with the same three lines `LockdownNotice` already
+ * establishes for "a thing is blocked, here is why and how it ends". The
+ * console surface for a blocked thing should not look different depending on
+ * which subsystem blocked it.
+ *
+ * Returns `null` below one refusal, so a quiet month renders nothing at all
+ * rather than a reassuring zero — the counter document exists from the first
+ * trip and never goes away, and "0 refused" on every subsequent month is
+ * noise that trains the owner to ignore the row that will one day be real.
+ */
+export declare function formSubmissionsPausedNotice(input: {
+    /** Refusals recorded for the month being displayed. */
+    refused: number;
+    /** The site's ceiling, from the counter document. Omitted if unknown. */
+    ceiling?: number;
+    now?: Date;
+}): FormsPausedOwnerNotice | null;

package/src/lib/app-utils/form-abuse-ceiling.js

@@ -0,0 +1,158 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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 two audiences of a tripped form-submission abuse ceiling (AGL-1666).
+ *
+ * AGL-1655 made the ceiling refuse correctly and bill nothing, but it refused
+ * into silence: the visitor got the component's generic "something went
+ * wrong" and the site's owner got a Firestore document. This module holds the
+ * words both of them see, in one place, because the two are constrained in
+ * OPPOSITE directions and a single file is the only way to keep that visible:
+ *
+ *  - The **visitor** is a stranger to the site. They must be told plainly
+ *    that their message did not arrive, and must NOT be told why — that this
+ *    site passed an abuse threshold is the owner's business, not a caller's.
+ *  - The **owner** needs exactly the withheld half: the count, the ceiling,
+ *    and when it lifts.
+ */ /**
+ * Refusal code carried by the abuse-ceiling 429 (AGL-1655).
+ *
+ * The Free plan's monthly wall answers 429 too, so the STATUS identifies
+ * nothing — this code is the whole discriminator, and one means "the customer
+ * needs a bigger plan" while the other means "this site is being flooded".
+ * Shared rather than restated so the producer and the consumer cannot drift.
+ */ export const FORM_ABUSE_CEILING_CODE = 'form-abuse-ceiling';
+/**
+ * The month key both the billable counter and the refusal counter are keyed
+ * by. UTC, matching the month boundary the ceiling resets on.
+ */ export function submissionMonthKey(now = new Date()) {
+    return now.toISOString().slice(0, 7);
+}
+/**
+ * The visitor's sentence.
+ *
+ * Three things it must not do, all of which the generic error branch did or
+ * a friendlier rewrite would:
+ *
+ *  1. **Not blame the visitor.** They filled in a form correctly. Nothing
+ *     about their message, their address or their retry is the reason.
+ *  2. **Not explain.** "Unusual volume", "temporarily over its limit", even
+ *     "this site is receiving too many messages" all tell a stranger
+ *     something about the site owner's account that the owner never chose to
+ *     publish. The refusal is the owner's problem to see, not the caller's.
+ *  3. **Not sound delivered.** "We'll get back to you", or anything ending
+ *     in a thank-you, converts a lost lead into a person waiting for a reply
+ *     that is never coming. So it says, in as many words, that the message
+ *     was not sent.
+ *
+ * What is left is short on purpose. The one genuinely useful thing to add is
+ * a door that still opens, which is why `contact` rides along.
+ */ export const FORM_UNAVAILABLE_MESSAGE = 'This form isn’t accepting messages right now, so your message was not ' + 'sent. Please try again later.';
+/**
+ * A site's published support address is author-written, so it is validated
+ * before being rendered as a link rather than trusted. Conservative on
+ * purpose: a rejected address costs the visitor a convenience, an accepted
+ * junk one costs them a bounced email and the site a lead it never learns it
+ * lost. The `mailto:` scheme is written by the renderer, not taken from here,
+ * so this is a plausibility check and not the injection defence.
+ */ const CONTACT_EMAIL_PATTERN = /^[^\s@<>"']+@[^\s@<>"'.]+(\.[^\s@<>"'.]+)+$/;
+/**
+ * Does this refused submit mean "this site's form is not accepting", rather
+ * than "something broke"?
+ *
+ * Takes the BODY only, deliberately. The obvious signature — `(status, body)`,
+ * matching `parseLockdownRefusal` — invites a caller to gate on the status
+ * first, and the status is precisely what does not distinguish this refusal
+ * from the Free plan's monthly wall. A caller holding only this function
+ * cannot make that mistake.
+ *
+ * Returns `null` for every other body, so a caller's existing generic error
+ * branch keeps handling real failures. Dressing a 500 as a deliberate pause
+ * would be the same class of lie in the other direction.
+ */ export function parseFormUnavailableRefusal(body) {
+    if (!body || typeof body !== 'object') return null;
+    const payload = body;
+    if (payload.code !== FORM_ABUSE_CEILING_CODE) return null;
+    const contact = typeof payload.contact === 'string' && payload.contact.trim() ? payload.contact.trim() : undefined;
+    return _extends({
+        message: FORM_UNAVAILABLE_MESSAGE
+    }, contact && CONTACT_EMAIL_PATTERN.test(contact) ? {
+        contact
+    } : {});
+}
+/**
+ * The moment the ceiling resets: 00:00 UTC on the first of next month, which
+ * is the same boundary AGL-1655's `Retry-After` points at and the same one
+ * the `YYYY-MM` counter key rolls over on.
+ */ export function formCeilingResetAt(now = new Date()) {
+    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1));
+}
+/**
+ * The honeypot's month, as the one sentence every surface renders (AGL-1831
+ * staff chip tooltip, AGL-1836 owner inbox notice).
+ *
+ * The framing is the point, and it is why the sentence lives here instead of
+ * in either component: the count reports the honeypot WORKING — caught and
+ * dropped, nothing stored, nothing billed — not something wrong. A surface
+ * that restated it could drift into alarm ("N spam attacks!") and train the
+ * owner to fear the number that should reassure them. It is also the
+ * AGL-1664 revisit input: spam creeping toward ~20% of a paying host's
+ * submissions is the trigger for reopening the App Check / CAPTCHA call.
+ *
+ * Returns `null` below one catch, same rule as `formSubmissionsPausedNotice`
+ * and for the same reason — the counter document persists from its first
+ * catch forever, and a reassuring zero trains the reader to ignore the row.
+ */ export function formSpamCaughtNotice(input) {
+    const spam = Math.floor(Number(input.spam) || 0);
+    if (spam < 1) return null;
+    return `${spam.toLocaleString()} bot submission${spam === 1 ? '' : 's'} ` + `${spam === 1 ? 'was' : 'were'} caught and dropped by the honeypot ` + `this month — nothing was stored or billed.`;
+}
+/**
+ * The owner's notice — the half deliberately withheld from the visitor.
+ *
+ * Shaped like `LockdownRefusalNotice` ({title, message, until}) so the
+ * console renders it with the same three lines `LockdownNotice` already
+ * establishes for "a thing is blocked, here is why and how it ends". The
+ * console surface for a blocked thing should not look different depending on
+ * which subsystem blocked it.
+ *
+ * Returns `null` below one refusal, so a quiet month renders nothing at all
+ * rather than a reassuring zero — the counter document exists from the first
+ * trip and never goes away, and "0 refused" on every subsequent month is
+ * noise that trains the owner to ignore the row that will one day be real.
+ */ export function formSubmissionsPausedNotice(input) {
+    var _input_now;
+    const refused = Math.floor(Number(input.refused) || 0);
+    if (refused < 1) return null;
+    const now = (_input_now = input.now) != null ? _input_now : new Date();
+    const ceiling = typeof input.ceiling === 'number' && Number.isFinite(input.ceiling) ? Math.floor(input.ceiling) : undefined;
+    const reset = formCeilingResetAt(now).toLocaleDateString(undefined, {
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric',
+        // The boundary is a UTC instant; rendering it in the reader's zone would
+        // move a 1 September reset to 31 August for most of the Americas.
+        timeZone: 'UTC'
+    });
+    return {
+        title: 'Form submissions are paused',
+        message: `${refused.toLocaleString()} submission${refused === 1 ? '' : 's'} ` + `to this site ${refused === 1 ? 'has' : 'have'} been refused this month` + (ceiling ? ` after it passed ${ceiling.toLocaleString()} submissions` : '') + '. Refused submissions are not stored and are not billed. This ' + 'usually means a bot is filling in one of your forms — if it is real ' + 'traffic, contact support and we will raise the limit.',
+        until: `Submissions start being accepted again on ${reset}.`
+    };
+}
+
+//# sourceMappingURL=form-abuse-ceiling.js.map

package/src/lib/app-utils/form-abuse-ceiling.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/form-abuse-ceiling.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * The two audiences of a tripped form-submission abuse ceiling (AGL-1666).\n *\n * AGL-1655 made the ceiling refuse correctly and bill nothing, but it refused\n * into silence: the visitor got the component's generic \"something went\n * wrong\" and the site's owner got a Firestore document. This module holds the\n * words both of them see, in one place, because the two are constrained in\n * OPPOSITE directions and a single file is the only way to keep that visible:\n *\n *  - The **visitor** is a stranger to the site. They must be told plainly\n *    that their message did not arrive, and must NOT be told why — that this\n *    site passed an abuse threshold is the owner's business, not a caller's.\n *  - The **owner** needs exactly the withheld half: the count, the ceiling,\n *    and when it lifts.\n */\n\n/**\n * Refusal code carried by the abuse-ceiling 429 (AGL-1655).\n *\n * The Free plan's monthly wall answers 429 too, so the STATUS identifies\n * nothing — this code is the whole discriminator, and one means \"the customer\n * needs a bigger plan\" while the other means \"this site is being flooded\".\n * Shared rather than restated so the producer and the consumer cannot drift.\n */\nexport const FORM_ABUSE_CEILING_CODE = 'form-abuse-ceiling'\n\n/**\n * The month key both the billable counter and the refusal counter are keyed\n * by. UTC, matching the month boundary the ceiling resets on.\n */\nexport function submissionMonthKey(now: Date = new Date()): string {\n  return now.toISOString().slice(0, 7)\n}\n\n/** What the visitor is shown when a site's form is not accepting. */\nexport interface FormUnavailableNotice {\n  /** The whole message. Fixed copy — never the server's terse `error`. */\n  message: string\n  /**\n   * An alternative way to reach the site, when the site publishes one\n   * (`business.supportEmail`, the token whose own description is \"where\n   * visitors should write for help\"). Absent when it does not.\n   */\n  contact?: string\n}\n\n/**\n * The visitor's sentence.\n *\n * Three things it must not do, all of which the generic error branch did or\n * a friendlier rewrite would:\n *\n *  1. **Not blame the visitor.** They filled in a form correctly. Nothing\n *     about their message, their address or their retry is the reason.\n *  2. **Not explain.** \"Unusual volume\", \"temporarily over its limit\", even\n *     \"this site is receiving too many messages\" all tell a stranger\n *     something about the site owner's account that the owner never chose to\n *     publish. The refusal is the owner's problem to see, not the caller's.\n *  3. **Not sound delivered.** \"We'll get back to you\", or anything ending\n *     in a thank-you, converts a lost lead into a person waiting for a reply\n *     that is never coming. So it says, in as many words, that the message\n *     was not sent.\n *\n * What is left is short on purpose. The one genuinely useful thing to add is\n * a door that still opens, which is why `contact` rides along.\n */\nexport const FORM_UNAVAILABLE_MESSAGE =\n  'This form isn’t accepting messages right now, so your message was not ' +\n  'sent. Please try again later.'\n\n/**\n * A site's published support address is author-written, so it is validated\n * before being rendered as a link rather than trusted. Conservative on\n * purpose: a rejected address costs the visitor a convenience, an accepted\n * junk one costs them a bounced email and the site a lead it never learns it\n * lost. The `mailto:` scheme is written by the renderer, not taken from here,\n * so this is a plausibility check and not the injection defence.\n */\nconst CONTACT_EMAIL_PATTERN = /^[^\\s@<>\"']+@[^\\s@<>\"'.]+(\\.[^\\s@<>\"'.]+)+$/\n\n/**\n * Does this refused submit mean \"this site's form is not accepting\", rather\n * than \"something broke\"?\n *\n * Takes the BODY only, deliberately. The obvious signature — `(status, body)`,\n * matching `parseLockdownRefusal` — invites a caller to gate on the status\n * first, and the status is precisely what does not distinguish this refusal\n * from the Free plan's monthly wall. A caller holding only this function\n * cannot make that mistake.\n *\n * Returns `null` for every other body, so a caller's existing generic error\n * branch keeps handling real failures. Dressing a 500 as a deliberate pause\n * would be the same class of lie in the other direction.\n */\nexport function parseFormUnavailableRefusal(\n  body: unknown,\n): FormUnavailableNotice | null {\n  if (!body || typeof body !== 'object') return null\n  const payload = body as { code?: unknown; contact?: unknown }\n  if (payload.code !== FORM_ABUSE_CEILING_CODE) return null\n  const contact =\n    typeof payload.contact === 'string' && payload.contact.trim()\n      ? payload.contact.trim()\n      : undefined\n  return {\n    message: FORM_UNAVAILABLE_MESSAGE,\n    ...(contact && CONTACT_EMAIL_PATTERN.test(contact) ? { contact } : {}),\n  }\n}\n\n/** What the site's owner is shown while their form is paused. */\nexport interface FormsPausedOwnerNotice {\n  title: string\n  /** What happened, how many, and that none of it is billed. */\n  message: string\n  /** When it lifts, as a local-reading sentence — never a raw month key. */\n  until: string\n}\n\n/**\n * The moment the ceiling resets: 00:00 UTC on the first of next month, which\n * is the same boundary AGL-1655's `Retry-After` points at and the same one\n * the `YYYY-MM` counter key rolls over on.\n */\nexport function formCeilingResetAt(now: Date = new Date()): Date {\n  return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1))\n}\n\n/**\n * The honeypot's month, as the one sentence every surface renders (AGL-1831\n * staff chip tooltip, AGL-1836 owner inbox notice).\n *\n * The framing is the point, and it is why the sentence lives here instead of\n * in either component: the count reports the honeypot WORKING — caught and\n * dropped, nothing stored, nothing billed — not something wrong. A surface\n * that restated it could drift into alarm (\"N spam attacks!\") and train the\n * owner to fear the number that should reassure them. It is also the\n * AGL-1664 revisit input: spam creeping toward ~20% of a paying host's\n * submissions is the trigger for reopening the App Check / CAPTCHA call.\n *\n * Returns `null` below one catch, same rule as `formSubmissionsPausedNotice`\n * and for the same reason — the counter document persists from its first\n * catch forever, and a reassuring zero trains the reader to ignore the row.\n */\nexport function formSpamCaughtNotice(input: { spam: number }): string | null {\n  const spam = Math.floor(Number(input.spam) || 0)\n  if (spam < 1) return null\n  return (\n    `${spam.toLocaleString()} bot submission${spam === 1 ? '' : 's'} ` +\n    `${spam === 1 ? 'was' : 'were'} caught and dropped by the honeypot ` +\n    `this month — nothing was stored or billed.`\n  )\n}\n\n/**\n * The owner's notice — the half deliberately withheld from the visitor.\n *\n * Shaped like `LockdownRefusalNotice` ({title, message, until}) so the\n * console renders it with the same three lines `LockdownNotice` already\n * establishes for \"a thing is blocked, here is why and how it ends\". The\n * console surface for a blocked thing should not look different depending on\n * which subsystem blocked it.\n *\n * Returns `null` below one refusal, so a quiet month renders nothing at all\n * rather than a reassuring zero — the counter document exists from the first\n * trip and never goes away, and \"0 refused\" on every subsequent month is\n * noise that trains the owner to ignore the row that will one day be real.\n */\nexport function formSubmissionsPausedNotice(input: {\n  /** Refusals recorded for the month being displayed. */\n  refused: number\n  /** The site's ceiling, from the counter document. Omitted if unknown. */\n  ceiling?: number\n  now?: Date\n}): FormsPausedOwnerNotice | null {\n  const refused = Math.floor(Number(input.refused) || 0)\n  if (refused < 1) return null\n  const now = input.now ?? new Date()\n  const ceiling =\n    typeof input.ceiling === 'number' && Number.isFinite(input.ceiling)\n      ? Math.floor(input.ceiling)\n      : undefined\n  const reset = formCeilingResetAt(now).toLocaleDateString(undefined, {\n    year: 'numeric',\n    month: 'long',\n    day: 'numeric',\n    // The boundary is a UTC instant; rendering it in the reader's zone would\n    // move a 1 September reset to 31 August for most of the Americas.\n    timeZone: 'UTC',\n  })\n  return {\n    title: 'Form submissions are paused',\n    message:\n      `${refused.toLocaleString()} submission${refused === 1 ? '' : 's'} ` +\n      `to this site ${refused === 1 ? 'has' : 'have'} been refused this month` +\n      (ceiling\n        ? ` after it passed ${ceiling.toLocaleString()} submissions`\n        : '') +\n      '. Refused submissions are not stored and are not billed. This ' +\n      'usually means a bot is filling in one of your forms — if it is real ' +\n      'traffic, contact support and we will raise the limit.',\n    until: `Submissions start being accepted again on ${reset}.`,\n  }\n}\n"],"names":["FORM_ABUSE_CEILING_CODE","submissionMonthKey","now","Date","toISOString","slice","FORM_UNAVAILABLE_MESSAGE","CONTACT_EMAIL_PATTERN","parseFormUnavailableRefusal","body","payload","code","contact","trim","undefined","message","test","formCeilingResetAt","UTC","getUTCFullYear","getUTCMonth","formSpamCaughtNotice","input","spam","Math","floor","Number","toLocaleString","formSubmissionsPausedNotice","refused","ceiling","isFinite","reset","toLocaleDateString","year","month","day","timeZone","title","until"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;CAcC,GAED;;;;;;;CAOC,GACD,OAAO,MAAMA,0BAA0B,qBAAoB;AAE3D;;;CAGC,GACD,OAAO,SAASC,mBAAmBC,MAAY,IAAIC,MAAM;IACvD,OAAOD,IAAIE,WAAW,GAAGC,KAAK,CAAC,GAAG;AACpC;AAcA;;;;;;;;;;;;;;;;;;;CAmBC,GACD,OAAO,MAAMC,2BACX,2EACA,gCAA+B;AAEjC;;;;;;;CAOC,GACD,MAAMC,wBAAwB;AAE9B;;;;;;;;;;;;;CAaC,GACD,OAAO,SAASC,4BACdC,IAAa;IAEb,IAAI,CAACA,QAAQ,OAAOA,SAAS,UAAU,OAAO;IAC9C,MAAMC,UAAUD;IAChB,IAAIC,QAAQC,IAAI,KAAKX,yBAAyB,OAAO;IACrD,MAAMY,UACJ,OAAOF,QAAQE,OAAO,KAAK,YAAYF,QAAQE,OAAO,CAACC,IAAI,KACvDH,QAAQE,OAAO,CAACC,IAAI,KACpBC;IACN,OAAO;QACLC,SAAST;OACLM,WAAWL,sBAAsBS,IAAI,CAACJ,WAAW;QAAEA;IAAQ,IAAI,CAAC;AAExE;AAWA;;;;CAIC,GACD,OAAO,SAASK,mBAAmBf,MAAY,IAAIC,MAAM;IACvD,OAAO,IAAIA,KAAKA,KAAKe,GAAG,CAAChB,IAAIiB,cAAc,IAAIjB,IAAIkB,WAAW,KAAK,GAAG;AACxE;AAEA;;;;;;;;;;;;;;;CAeC,GACD,OAAO,SAASC,qBAAqBC,KAAuB;IAC1D,MAAMC,OAAOC,KAAKC,KAAK,CAACC,OAAOJ,MAAMC,IAAI,KAAK;IAC9C,IAAIA,OAAO,GAAG,OAAO;IACrB,OACE,GAAGA,KAAKI,cAAc,GAAG,eAAe,EAAEJ,SAAS,IAAI,KAAK,IAAI,CAAC,CAAC,GAClE,GAAGA,SAAS,IAAI,QAAQ,OAAO,oCAAoC,CAAC,GACpE,CAAC,0CAA0C,CAAC;AAEhD;AAEA;;;;;;;;;;;;;CAaC,GACD,OAAO,SAASK,4BAA4BN,KAM3C;QAGaA;IAFZ,MAAMO,UAAUL,KAAKC,KAAK,CAACC,OAAOJ,MAAMO,OAAO,KAAK;IACpD,IAAIA,UAAU,GAAG,OAAO;IACxB,MAAM3B,OAAMoB,aAAAA,MAAMpB,GAAG,YAAToB,aAAa,IAAInB;IAC7B,MAAM2B,UACJ,OAAOR,MAAMQ,OAAO,KAAK,YAAYJ,OAAOK,QAAQ,CAACT,MAAMQ,OAAO,IAC9DN,KAAKC,KAAK,CAACH,MAAMQ,OAAO,IACxBhB;IACN,MAAMkB,QAAQf,mBAAmBf,KAAK+B,kBAAkB,CAACnB,WAAW;QAClEoB,MAAM;QACNC,OAAO;QACPC,KAAK;QACL,yEAAyE;QACzE,kEAAkE;QAClEC,UAAU;IACZ;IACA,OAAO;QACLC,OAAO;QACPvB,SACE,GAAGc,QAAQF,cAAc,GAAG,WAAW,EAAEE,YAAY,IAAI,KAAK,IAAI,CAAC,CAAC,GACpE,CAAC,aAAa,EAAEA,YAAY,IAAI,QAAQ,OAAO,wBAAwB,CAAC,GACvEC,CAAAA,UACG,CAAC,iBAAiB,EAAEA,QAAQH,cAAc,GAAG,YAAY,CAAC,GAC1D,EAAC,IACL,mEACA,yEACA;QACFY,OAAO,CAAC,0CAA0C,EAAEP,MAAM,CAAC,CAAC;IAC9D;AACF"}

package/src/lib/app-utils/form-contract.d.ts

@@ -0,0 +1,198 @@
+/**
+ * @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.
+ */
+/**
+ * What a form's DESIGN must still satisfy for its submissions to arrive.
+ *
+ * A reusable component is only ever drawn: the worst an author can do to one
+ * is make it ugly, and the page still renders. A form is drawn AND it is a
+ * contract — `/api/forms/submit` keys submissions on its id, reads consent out
+ * of a field it names, and creates a lead from an address it expects to find.
+ * Every one of those couplings is resolved by NAME at submit time, so the
+ * design can break them, and breaking them is silent in every case: the form
+ * still renders, the visitor still submits, the row still lands, and the thing
+ * the merchant believed they were collecting is simply not there.
+ *
+ * That asymmetry is the whole reason this module exists. Publishing a form is
+ * not "save the drawing"; it is "promise the server can still read this".
+ *
+ * ## The six silent failures, and why each one is checked here
+ *
+ * Every check below corresponds to something a design can do that produces NO
+ * error at submit time. A design that fails loudly needs no guard — the author
+ * finds out. These are the ones where nobody finds out.
+ *
+ *  1. **The form node stops naming this form.** Submissions carry `formId` and
+ *     the route stamps it only after verifying it against this host's forms;
+ *     the Inbox's per-form list is an equality on it. Clear or rebind it and
+ *     every later submission is unattributable — while still landing in the
+ *     Inbox, so nothing looks broken and the form's own list just stops
+ *     growing.
+ *  2. **A field with no name.** `formFieldDeclsFromNodes` drops it, and the
+ *     runtime falls back to `name = fieldName || 'field'`, so several unnamed
+ *     inputs collapse onto ONE submission key. The visitor types, the value is
+ *     posted, and it is not retrievable under any name the author knows.
+ *  3. **Two fields sharing a name.** `FormData` joins entries under one key,
+ *     so the second input contributes no separate value and the declaration
+ *     keeps only the first. Two questions, one answer.
+ *  4. **Lead routing with nothing to extract an address from.**
+ *     `routing.lead` only ever fires when `extractEmailFromFields` finds one,
+ *     and that prefers a key matching `/email/i` before falling back to any
+ *     email-shaped value. A form with no such field can still route to leads
+ *     on paper and never create one.
+ *  5. **Lead routing with nothing that records consent.** The route files
+ *     the lead either way, and stamps an opt-in on it only from the field the
+ *     form declares or from an undeclared field on the closed name list it
+ *     falls back to. A form with neither files leads nobody may email — the
+ *     send-time consent join refuses every one — so the sales team works a
+ *     list the campaigns cannot reach, and nothing at submit time says so.
+ *  6. **A consent field that no longer exists.** `readFormDeclaredConsent`
+ *     looks up exactly `consentFieldName`. Rename or delete that field and it
+ *     returns `false` forever — the form keeps collecting the tick and the
+ *     opt-in stops being recorded. This is the one with consequences outside
+ *     the product, since an advertising basis that quietly stops is
+ *     indistinguishable downstream from one that was never given.
+ *
+ * ## What is NOT checked
+ *
+ * Anything the author can see. A missing label, an empty select, a field in
+ * the wrong order — those are visible on the canvas and are the author's to
+ * judge. This module is only for couplings that are invisible at design time
+ * and asymptomatic at run time.
+ *
+ * Pure and dependency-free, like `forms.ts` beside it: it reaches client
+ * bundles through `app-utils/index`, so nothing here may import a Node
+ * builtin.
+ */
+import type { AglynNodeSchema, NodeId } from '../foundation/definitions/components.types';
+import { type FormDocument } from './forms';
+/**
+ * Which coupling a violation is about.
+ *
+ * A code rather than a message so a caller can decide presentation — the
+ * besigner shows these beside the offending node, the API route puts them in
+ * a 422 body — without either one parsing prose.
+ */
+export type FormContractViolationCode = 'forms-off-for-site' | 'form-node-missing' | 'form-id-unbound' | 'field-unnamed' | 'field-name-duplicated' | 'lead-routing-has-no-email-field' | 'lead-routing-has-no-consent-field' | 'consent-field-missing';
+/** One way this design would fail to keep the server's side of the bargain. */
+export interface FormContractViolation {
+    code: FormContractViolationCode;
+    /** The node the author has to fix, when a single node is at fault. */
+    nodeId?: NodeId;
+    /** The name at issue, for the two checks that are about names. */
+    fieldName?: string;
+    /** Author-facing, and stated as the CONSEQUENCE rather than the rule. */
+    message: string;
+}
+/**
+ * Whether a submission carrying these fields could yield an address to key
+ * a lead on — the one precondition of lead routing (AGL-2612).
+ *
+ * Exported because the check is asked in two places that never see a node
+ * tree: the form's own page decides whether to offer the routing switch, and
+ * the CRM's Leads section offers to turn routing on for a form from the
+ * declared field list alone. Both must agree with the publish check here or
+ * a switch flipped on one surface is refused on the next.
+ */
+export declare function formFieldsCanYieldAnEmail(fields: ReadonlyArray<{
+    fieldName: string;
+    fieldType: string;
+}>): boolean;
+/**
+ * Whether a submission carrying these fields could record an opt-in — the
+ * other precondition of lead routing, and the one that decides whether a
+ * lead is worth filing: a lead nobody consented with is one the campaigns
+ * refuse at send time.
+ *
+ * Consent is recorded from the field the form DECLARES, or, when it declares
+ * none, from an undeclared field the route recognizes by name. Whether a
+ * declared field still exists is `consent-field-missing`'s question, asked
+ * separately so a lost field is reported once, as the loss it is.
+ *
+ * Exported for the same two surfaces as {@link formFieldsCanYieldAnEmail}:
+ * the switch on the form's page and the Leads section's offer must refuse
+ * what the publish check would refuse.
+ */
+export declare function formFieldsCaptureConsent(fields: ReadonlyArray<{
+    fieldName: string;
+}>, consentFieldName: string | null | undefined): boolean;
+/**
+ * A site that switched Forms off (AGL-3029) publishes no form — neither a form
+ * design nor a page, layout or component that carries one.
+ *
+ * Not one of the six silent failures above, and checked ahead of all of them:
+ * on such a site the published page does not draw a form and `/api/forms/submit`
+ * refuses every submission, so publishing one would put a hole on a live page
+ * while the author believed they had shipped a form. Refusing it is what makes
+ * the empty space on a page published BEFORE the switch the only kind there is.
+ */
+export declare const FORMS_OFF_FOR_SITE_VIOLATION: FormContractViolation;
+/**
+ * Whether a node map carries a form: a `form` node anywhere in it, bound to
+ * an entity or drawn inline. Read by `componentId`, which every form node has
+ * carried from the start, rather than by the `pluginId` a node was stamped
+ * with when it was placed.
+ */
+export declare function nodesCarryForm(nodes: Record<NodeId, AglynNodeSchema | undefined> | undefined | null): boolean;
+/**
+ * The same refusal, for a page, layout or component that CARRIES a form: the
+ * sentence names the two ways forward, because removing the form publishes
+ * the rest of the page.
+ */
+export declare const FORMS_OFF_FOR_SITE_PAGE_VIOLATION: FormContractViolation;
+/**
+ * The refusal for publishing a page, layout or component that carries a form
+ * on a site that switched Forms off, or `null` (AGL-3029). `formsOnForSite`
+ * absent means the caller could not tell, which refuses nothing.
+ */
+export declare function formsOffPublishViolation(nodes: Record<NodeId, AglynNodeSchema | undefined> | undefined | null, formsOnForSite: boolean | undefined): FormContractViolation | null;
+/**
+ * Everything this design would break, or an empty array.
+ *
+ * @param options.form      the stored document, for what it ROUTES and what it
+ *                          names as its consent field. `routing` and
+ *                          `consentFieldName` are the only two parts read: the
+ *                          stored `fields` are the previous design's output,
+ *                          not a contract the new one owes anything to.
+ * @param options.formId    the id this design is the design OF.
+ * @param options.nodes     the flat node map, canvas or published.
+ * @param options.formNodeId the `form` node inside it.
+ * @param options.formsOnForSite whether Forms runs on the site the form is
+ *                      published to; `false` refuses the design outright.
+ *                      Absent, the caller could not tell, and nothing is
+ *                      refused for it.
+ */
+export declare function checkFormContract(options: {
+    form: Pick<FormDocument, 'routing' | 'consentFieldName'> | null | undefined;
+    formId: string;
+    nodes: Record<NodeId, AglynNodeSchema | undefined> | undefined | null;
+    formNodeId: NodeId | undefined | null;
+    /** Overridable for a host whose plugin registers these under other ids. */
+    componentIds?: {
+        form?: string;
+        formField?: string;
+    };
+    formsOnForSite?: boolean;
+}): FormContractViolation[];
+/**
+ * Whether this design may be published.
+ *
+ * Every violation is blocking. There is no advisory tier because there is no
+ * violation here an author would be right to ship: each one names data that
+ * silently fails to arrive, and a warning that can be clicked past is how a
+ * silent failure ships anyway.
+ */
+export declare function formContractIsSatisfied(violations: FormContractViolation[]): boolean;