@aglyn/plugins-forms 1.0.0-beta.218 → 1.0.0-beta.219

package/src/lib/server/form-promote-route.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @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.
+ */
+import { type PluginWebApiHandler } from '@aglyn/aglyn/server';
+/**
+ * PROMOTING A FORM: make one version the one the site serves.
+ *
+ * ## What promotion means, and why a form cannot borrow the component answer
+ *
+ * A reusable component's parent document IS the published copy — the tenant
+ * reads every component's tree in one collection query on each render, which
+ * is what keeps composing a page to a single read — so promoting a component
+ * is a copy of the version's tree onto the parent plus a move of the
+ * `versionId` pointer. A form is stored the same way for the same reason, so
+ * the mechanics look identical: copy `nodes`, carry `rootId`, move the
+ * pointer.
+ *
+ * They are not identical, and the difference is the whole reason this is a
+ * server route rather than one more `updateDoc` in a card. A component is only
+ * ever DRAWN: the worst a bad promotion does is make a page ugly, and the page
+ * still renders. A form is drawn AND it is a contract — `/api/forms/submit`
+ * keys submissions on the id the form node carries, reads marketing consent
+ * out of a field the document 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 a 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 not
+ * there.
+ *
+ * So promotion RUNS `checkFormContract` against the tree it is about to write,
+ * and a violation refuses the write with the violations in the body. The
+ * besigner's own Save & publish runs the same check for the same reason; this
+ * route exists because promotion must also be reachable from the form's page,
+ * where an author picks a version out of history and never opens the canvas
+ * at all — and a second promotion path that skipped the check would make the
+ * check optional.
+ *
+ * ## Why the check runs HERE and not only in the browser
+ *
+ * The rules can express "only a publisher may move `versionId`". They cannot
+ * express "and only if the tree you are moving it to still names its own
+ * fields", because that is a walk of a compressed node map. A console-side
+ * check is advice; this is the enforcement, and it is the reason the route
+ * reads the version document itself rather than accepting a tree from the
+ * caller. Nothing about the design crosses the wire inbound — a client that
+ * could send its own `nodes` could send a tree that passes the check and
+ * publish a different one.
+ *
+ * `POST /api/forms/promote`, served by the console's plugin API dispatcher,
+ * which has already refused an unverified account, a locked-down site or
+ * organization and a site that switched Forms off before this runs. It is the
+ * route `plugins.config.json` names as a form's `besignerDocuments` publish,
+ * so the besigner's Save & publish and the form page's version history reach
+ * the same check.
+ *
+ * Body: `{ hostId, formId, versionId }`.
+ * 422 with `{ violations }` when the contract would break; the shape is the
+ * pure module's own, so the console renders the same sentences the besigner
+ * does without either side parsing prose.
+ */
+export declare const formPromoteHandler: PluginWebApiHandler;

package/src/lib/server/form-promote-route.js

@@ -0,0 +1,239 @@
+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.
+ */ import { encodeStoredNodes, hostRoleCanPublish, isHostPluginEnabled, pluginRequestFromWeb } from "@aglyn/aglyn/server";
+import { emailUnverifiedResponse, firebaseAdmin, getOrgForHost, isImpersonationSession, logHostActivity } from "@aglyn/tenant-data-admin";
+import { isRefusedIdToken } from "@aglyn/tenant-data-admin/server/id-token-refusal";
+import { Timestamp } from "firebase-admin/firestore";
+import { BUNDLE_ID } from "../constants/bundle-common.js";
+import { isFormPromotionRefusal, resolveFormPromotion } from "./form-promotion.js";
+import { announceFormPublish } from "./form-publish-announce.js";
+/**
+ * PROMOTING A FORM: make one version the one the site serves.
+ *
+ * ## What promotion means, and why a form cannot borrow the component answer
+ *
+ * A reusable component's parent document IS the published copy — the tenant
+ * reads every component's tree in one collection query on each render, which
+ * is what keeps composing a page to a single read — so promoting a component
+ * is a copy of the version's tree onto the parent plus a move of the
+ * `versionId` pointer. A form is stored the same way for the same reason, so
+ * the mechanics look identical: copy `nodes`, carry `rootId`, move the
+ * pointer.
+ *
+ * They are not identical, and the difference is the whole reason this is a
+ * server route rather than one more `updateDoc` in a card. A component is only
+ * ever DRAWN: the worst a bad promotion does is make a page ugly, and the page
+ * still renders. A form is drawn AND it is a contract — `/api/forms/submit`
+ * keys submissions on the id the form node carries, reads marketing consent
+ * out of a field the document 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 a 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 not
+ * there.
+ *
+ * So promotion RUNS `checkFormContract` against the tree it is about to write,
+ * and a violation refuses the write with the violations in the body. The
+ * besigner's own Save & publish runs the same check for the same reason; this
+ * route exists because promotion must also be reachable from the form's page,
+ * where an author picks a version out of history and never opens the canvas
+ * at all — and a second promotion path that skipped the check would make the
+ * check optional.
+ *
+ * ## Why the check runs HERE and not only in the browser
+ *
+ * The rules can express "only a publisher may move `versionId`". They cannot
+ * express "and only if the tree you are moving it to still names its own
+ * fields", because that is a walk of a compressed node map. A console-side
+ * check is advice; this is the enforcement, and it is the reason the route
+ * reads the version document itself rather than accepting a tree from the
+ * caller. Nothing about the design crosses the wire inbound — a client that
+ * could send its own `nodes` could send a tree that passes the check and
+ * publish a different one.
+ *
+ * `POST /api/forms/promote`, served by the console's plugin API dispatcher,
+ * which has already refused an unverified account, a locked-down site or
+ * organization and a site that switched Forms off before this runs. It is the
+ * route `plugins.config.json` names as a form's `besignerDocuments` publish,
+ * so the besigner's Save & publish and the form page's version history reach
+ * the same check.
+ *
+ * Body: `{ hostId, formId, versionId }`.
+ * 422 with `{ violations }` when the contract would break; the shape is the
+ * pure module's own, so the console renders the same sentences the besigner
+ * does without either side parsing prose.
+ */ export const formPromoteHandler = async (request)=>{
+    var _headers_authorization, _ref, _ref1, _ref2;
+    const { method, body, headers: rawHeaders } = await pluginRequestFromWeb(request);
+    const headers = rawHeaders;
+    if (method !== 'POST') {
+        return Response.json({
+            error: 'Method not allowed'
+        }, {
+            status: 405
+        });
+    }
+    const authorization = (_headers_authorization = headers.authorization) != null ? _headers_authorization : '';
+    const idToken = authorization.startsWith('Bearer ') ? authorization.slice('Bearer '.length) : undefined;
+    if (!idToken) return Response.json({
+        error: 'Unauthenticated'
+    }, {
+        status: 401
+    });
+    const hostId = String((_ref = body == null ? void 0 : body.hostId) != null ? _ref : '');
+    const formId = String((_ref1 = body == null ? void 0 : body.formId) != null ? _ref1 : '');
+    const versionId = String((_ref2 = body == null ? void 0 : body.versionId) != null ? _ref2 : '');
+    if (!hostId || !formId || !versionId) {
+        return Response.json({
+            error: 'Missing hostId, formId or versionId'
+        }, {
+            status: 400
+        });
+    }
+    try {
+        var _hostSnapshot_get, _ref3;
+        const decoded = await firebaseAdmin.app().auth().verifyIdToken(idToken);
+        if (!decoded.email_verified && !isImpersonationSession(decoded)) {
+            return emailUnverifiedResponse();
+        }
+        const firestore = firebaseAdmin.app().firestore();
+        const hostRef = firestore.collection('hosts').doc(hostId);
+        const hostSnapshot = await hostRef.get();
+        if (!hostSnapshot.exists) {
+            return Response.json({
+                error: 'Unknown site'
+            }, {
+                status: 404
+            });
+        }
+        // PUBLISH, not write. The `author` role edits content and may not make it
+        // live — the same line the rules draw at `canPublishHostContent`, and the
+        // reason this is `hostRoleCanPublish` rather than the `hostRoleCanWrite`
+        // the version-create route next door uses: creating a draft version
+        // changes nothing a visitor sees, and moving the pointer is the act that
+        // does.
+        const memberRole = ((_hostSnapshot_get = hostSnapshot.get('memberRoles')) != null ? _hostSnapshot_get : {})[decoded.uid];
+        if (!hostRoleCanPublish(memberRole)) {
+            return Response.json({
+                error: 'Publishing requires the editor or admin role'
+            }, {
+                status: 403
+            });
+        }
+        const ownerOrg = await getOrgForHost(hostId);
+        const org = (_ref3 = ownerOrg == null ? void 0 : ownerOrg.org) != null ? _ref3 : {};
+        const formRef = hostRef.collection('forms').doc(formId);
+        const [formSnapshot, versionSnapshot] = await Promise.all([
+            formRef.get(),
+            formRef.collection('versions').doc(versionId).get()
+        ]);
+        if (!formSnapshot.exists) {
+            return Response.json({
+                error: 'Unknown form'
+            }, {
+                status: 404
+            });
+        }
+        if (!versionSnapshot.exists) {
+            return Response.json({
+                error: 'Unknown version'
+            }, {
+                status: 404
+            });
+        }
+        /*
+     * THE CHECK, BEFORE THE WRITE — and it is the same decision the besigner's
+     * publish makes, in one shared module, so the two promotion paths cannot
+     * disagree about which designs may ship.
+     */ const resolved = resolveFormPromotion({
+            formId,
+            form: formSnapshot.data(),
+            storedNodes: versionSnapshot.get('nodes'),
+            // The site's own plugin set (AGL-3029): a site that switched Forms off
+            // does not draw a form or accept its submissions, so none goes live.
+            formsOnForSite: isHostPluginEnabled(org, hostSnapshot.data(), BUNDLE_ID)
+        });
+        if (isFormPromotionRefusal(resolved)) {
+            return Response.json(resolved.body, {
+                status: resolved.status
+            });
+        }
+        await formRef.update(_extends({
+            // Compressed at rest (AGL-1151). `resolveFormPromotion` hands back the
+            // DECODED tree because the contract check has to walk it; the storage
+            // form is decided here, at the write, and matches what the besigner's
+            // own publish writes to this same document.
+            nodes: Buffer.from(encodeStoredNodes(resolved.nodes))
+        }, resolved.rootId ? {
+            rootId: resolved.rootId
+        } : {}, {
+            fields: resolved.fields,
+            versionId,
+            updatedAt: Timestamp.now()
+        }));
+        /*
+     * The pages that place this form are now serving fields it no longer has.
+     *
+     * Fired without awaiting, exactly as the component publish path does: the
+     * write above already succeeded, the scan reads every screen, layout and
+     * component on the site, and nobody is watching one URL for a form publish
+     * the way they watch a page after publishing it. `announceFormPublish`
+     * absorbs its own failures — the render cache's TTL is the backstop.
+     */ void announceFormPublish({
+            firestore,
+            hostId,
+            formId
+        });
+        // A form files under `content`: `HostActivityTarget['type']` is a
+        // PERSISTED value `activity-presenter.ts` branches on, and a member no
+        // presenter knows renders as an unlinked row.
+        await logHostActivity(hostId, {
+            uid: decoded.uid,
+            email: decoded.email ? String(decoded.email) : null
+        }, 'Published a version of the form', _extends({
+            type: 'content',
+            id: formId,
+            versionId
+        }, formSnapshot.get('displayName') ? {
+            name: String(formSnapshot.get('displayName'))
+        } : {}));
+        return Response.json({
+            ok: true,
+            versionId
+        }, {
+            status: 200
+        });
+    } catch (error) {
+        // A refused credential is a 401, not a fault of ours (AGL-1993); anything
+        // else keeps the answer below.
+        if (isRefusedIdToken(error)) {
+            return Response.json({
+                error: 'Unauthenticated'
+            }, {
+                status: 401
+            });
+        }
+        console.error('[forms] publish failed', error);
+        return Response.json({
+            error: 'Publish failed'
+        }, {
+            status: 500
+        });
+    }
+};
+
+//# sourceMappingURL=form-promote-route.js.map

package/src/lib/server/form-promote-route.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/forms/src/lib/server/form-promote-route.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\nimport {\n  encodeStoredNodes,\n  hostRoleCanPublish,\n  isHostPluginEnabled,\n  pluginRequestFromWeb,\n  type PluginWebApiHandler,\n} from '@aglyn/aglyn/server'\nimport {\n  emailUnverifiedResponse,\n  firebaseAdmin,\n  getOrgForHost,\n  isImpersonationSession,\n  logHostActivity,\n} from '@aglyn/tenant-data-admin'\nimport { isRefusedIdToken } from '@aglyn/tenant-data-admin/server/id-token-refusal'\nimport { Timestamp } from 'firebase-admin/firestore'\nimport { BUNDLE_ID } from '../constants/bundle-common'\nimport { isFormPromotionRefusal, resolveFormPromotion } from './form-promotion'\nimport { announceFormPublish } from './form-publish-announce'\n\n/**\n * PROMOTING A FORM: make one version the one the site serves.\n *\n * ## What promotion means, and why a form cannot borrow the component answer\n *\n * A reusable component's parent document IS the published copy — the tenant\n * reads every component's tree in one collection query on each render, which\n * is what keeps composing a page to a single read — so promoting a component\n * is a copy of the version's tree onto the parent plus a move of the\n * `versionId` pointer. A form is stored the same way for the same reason, so\n * the mechanics look identical: copy `nodes`, carry `rootId`, move the\n * pointer.\n *\n * They are not identical, and the difference is the whole reason this is a\n * server route rather than one more `updateDoc` in a card. A component is only\n * ever DRAWN: the worst a bad promotion does is make a page ugly, and the page\n * still renders. A form is drawn AND it is a contract — `/api/forms/submit`\n * keys submissions on the id the form node carries, reads marketing consent\n * out of a field the document NAMES, and creates a lead from an address it\n * expects to find. Every one of those couplings is resolved by NAME at submit\n * time, so a design can break them, and breaking them is silent in every\n * case: the form still renders, the visitor still submits, the row still\n * lands, and the thing the merchant believed they were collecting is not\n * there.\n *\n * So promotion RUNS `checkFormContract` against the tree it is about to write,\n * and a violation refuses the write with the violations in the body. The\n * besigner's own Save & publish runs the same check for the same reason; this\n * route exists because promotion must also be reachable from the form's page,\n * where an author picks a version out of history and never opens the canvas\n * at all — and a second promotion path that skipped the check would make the\n * check optional.\n *\n * ## Why the check runs HERE and not only in the browser\n *\n * The rules can express \"only a publisher may move `versionId`\". They cannot\n * express \"and only if the tree you are moving it to still names its own\n * fields\", because that is a walk of a compressed node map. A console-side\n * check is advice; this is the enforcement, and it is the reason the route\n * reads the version document itself rather than accepting a tree from the\n * caller. Nothing about the design crosses the wire inbound — a client that\n * could send its own `nodes` could send a tree that passes the check and\n * publish a different one.\n *\n * `POST /api/forms/promote`, served by the console's plugin API dispatcher,\n * which has already refused an unverified account, a locked-down site or\n * organization and a site that switched Forms off before this runs. It is the\n * route `plugins.config.json` names as a form's `besignerDocuments` publish,\n * so the besigner's Save & publish and the form page's version history reach\n * the same check.\n *\n * Body: `{ hostId, formId, versionId }`.\n * 422 with `{ violations }` when the contract would break; the shape is the\n * pure module's own, so the console renders the same sentences the besigner\n * does without either side parsing prose.\n */\nexport const formPromoteHandler: PluginWebApiHandler = async (request) => {\n  const { method, body, headers: rawHeaders } = await pluginRequestFromWeb(request)\n  const headers = rawHeaders as Partial<Record<string, string>>\n  if (method !== 'POST') {\n    return Response.json({ error: 'Method not allowed' }, { status: 405 })\n  }\n  const authorization = headers.authorization ?? ''\n  const idToken = authorization.startsWith('Bearer ')\n    ? authorization.slice('Bearer '.length)\n    : undefined\n  if (!idToken) return Response.json({ error: 'Unauthenticated' }, { status: 401 })\n\n  const hostId = String(body?.hostId ?? '')\n  const formId = String(body?.formId ?? '')\n  const versionId = String(body?.versionId ?? '')\n  if (!hostId || !formId || !versionId) {\n    return Response.json(\n      { error: 'Missing hostId, formId or versionId' },\n      { status: 400 },\n    )\n  }\n\n  try {\n    const decoded = await firebaseAdmin.app().auth().verifyIdToken(idToken)\n    if (!decoded.email_verified && !isImpersonationSession(decoded)) {\n      return emailUnverifiedResponse()\n    }\n    const firestore = firebaseAdmin.app().firestore()\n    const hostRef = firestore.collection('hosts').doc(hostId)\n    const hostSnapshot = await hostRef.get()\n    if (!hostSnapshot.exists) {\n      return Response.json({ error: 'Unknown site' }, { status: 404 })\n    }\n    // PUBLISH, not write. The `author` role edits content and may not make it\n    // live — the same line the rules draw at `canPublishHostContent`, and the\n    // reason this is `hostRoleCanPublish` rather than the `hostRoleCanWrite`\n    // the version-create route next door uses: creating a draft version\n    // changes nothing a visitor sees, and moving the pointer is the act that\n    // does.\n    const memberRole = (hostSnapshot.get('memberRoles') ?? {})[decoded.uid]\n    if (!hostRoleCanPublish(memberRole)) {\n      return Response.json(\n        { error: 'Publishing requires the editor or admin role' },\n        { status: 403 },\n      )\n    }\n\n    const ownerOrg = await getOrgForHost(hostId)\n    const org = (ownerOrg?.org ?? {}) as { enabledPlugins?: string[] }\n\n    const formRef = hostRef.collection('forms').doc(formId)\n    const [formSnapshot, versionSnapshot] = await Promise.all([\n      formRef.get(),\n      formRef.collection('versions').doc(versionId).get(),\n    ])\n    if (!formSnapshot.exists) {\n      return Response.json({ error: 'Unknown form' }, { status: 404 })\n    }\n    if (!versionSnapshot.exists) {\n      return Response.json({ error: 'Unknown version' }, { status: 404 })\n    }\n\n    /*\n     * THE CHECK, BEFORE THE WRITE — and it is the same decision the besigner's\n     * publish makes, in one shared module, so the two promotion paths cannot\n     * disagree about which designs may ship.\n     */\n    const resolved = resolveFormPromotion({\n      formId,\n      form: formSnapshot.data() as Record<string, unknown>,\n      storedNodes: versionSnapshot.get('nodes'),\n      // The site's own plugin set (AGL-3029): a site that switched Forms off\n      // does not draw a form or accept its submissions, so none goes live.\n      formsOnForSite: isHostPluginEnabled(org, hostSnapshot.data(), BUNDLE_ID),\n    })\n    if (isFormPromotionRefusal(resolved)) {\n      return Response.json(resolved.body, { status: resolved.status })\n    }\n\n    await formRef.update({\n      // Compressed at rest (AGL-1151). `resolveFormPromotion` hands back the\n      // DECODED tree because the contract check has to walk it; the storage\n      // form is decided here, at the write, and matches what the besigner's\n      // own publish writes to this same document.\n      nodes: Buffer.from(encodeStoredNodes(resolved.nodes)!),\n      ...(resolved.rootId ? { rootId: resolved.rootId } : {}),\n      fields: resolved.fields,\n      versionId,\n      updatedAt: Timestamp.now(),\n    })\n    /*\n     * The pages that place this form are now serving fields it no longer has.\n     *\n     * Fired without awaiting, exactly as the component publish path does: the\n     * write above already succeeded, the scan reads every screen, layout and\n     * component on the site, and nobody is watching one URL for a form publish\n     * the way they watch a page after publishing it. `announceFormPublish`\n     * absorbs its own failures — the render cache's TTL is the backstop.\n     */\n    void announceFormPublish({ firestore, hostId, formId })\n    // A form files under `content`: `HostActivityTarget['type']` is a\n    // PERSISTED value `activity-presenter.ts` branches on, and a member no\n    // presenter knows renders as an unlinked row.\n    await logHostActivity(\n      hostId,\n      { uid: decoded.uid, email: decoded.email ? String(decoded.email) : null },\n      'Published a version of the form',\n      {\n        type: 'content',\n        id: formId,\n        versionId,\n        ...(formSnapshot.get('displayName')\n          ? { name: String(formSnapshot.get('displayName')) }\n          : {}),\n      },\n    )\n    return Response.json({ ok: true, versionId }, { status: 200 })\n  } catch (error) {\n    // A refused credential is a 401, not a fault of ours (AGL-1993); anything\n    // else keeps the answer below.\n    if (isRefusedIdToken(error)) {\n      return Response.json({ error: 'Unauthenticated' }, { status: 401 })\n    }\n    console.error('[forms] publish failed', error)\n    return Response.json({ error: 'Publish failed' }, { status: 500 })\n  }\n}\n"],"names":["encodeStoredNodes","hostRoleCanPublish","isHostPluginEnabled","pluginRequestFromWeb","emailUnverifiedResponse","firebaseAdmin","getOrgForHost","isImpersonationSession","logHostActivity","isRefusedIdToken","Timestamp","BUNDLE_ID","isFormPromotionRefusal","resolveFormPromotion","announceFormPublish","formPromoteHandler","request","headers","method","body","rawHeaders","Response","json","error","status","authorization","idToken","startsWith","slice","length","undefined","hostId","String","formId","versionId","hostSnapshot","decoded","app","auth","verifyIdToken","email_verified","firestore","hostRef","collection","doc","get","exists","memberRole","uid","ownerOrg","org","formRef","formSnapshot","versionSnapshot","Promise","all","resolved","form","data","storedNodes","formsOnForSite","update","nodes","Buffer","from","rootId","fields","updatedAt","now","email","type","id","name","ok","console"],"mappings":"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"}

package/src/lib/server/form-promotion.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @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.
+ */
+import { type FormContractViolation, type FormFieldDecl } from '@aglyn/aglyn/server';
+/** A promotion that must not happen, and what to tell the author. */
+export interface FormPromotionRefusal {
+    status: number;
+    body: {
+        error: string;
+        /**
+         * The contract violations, when that is what refused it.
+         *
+         * The pure module's own shape, so a caller renders the same sentences the
+         * besigner does without either side parsing prose. Absent on the two
+         * refusals that are about the CANVAS rather than the contract.
+         */
+        violations?: FormContractViolation[];
+    };
+}
+/** Exactly the fields a promotion writes onto the form document. */
+export interface FormPromotionWrite {
+    rootId?: string;
+    nodes: Record<string, any>;
+    fields: FormFieldDecl[];
+}
+/** Whether this answer is the refusal. */
+export declare function isFormPromotionRefusal(result: FormPromotionWrite | FormPromotionRefusal): result is FormPromotionRefusal;
+/**
+ * WHAT A PROMOTION WOULD WRITE, OR WHY IT MUST NOT HAPPEN.
+ *
+ * Promoting a form is not "copy the drawing onto the parent". A reusable
+ * component's promotion is exactly that, because a component is only ever
+ * DRAWN — the worst a bad one does is make a page ugly, and the page still
+ * renders. A form is drawn AND it is a contract: `/api/forms/submit` keys
+ * submissions on the id the form node carries, reads marketing consent out of
+ * a field the document 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 every break is silent — the form renders, the
+ * visitor submits, the row lands, and the thing the merchant believed they
+ * were collecting is not there.
+ *
+ * So this decides, before any write exists to undo, and it decides in one
+ * place because there are two ways to reach a promotion: the besigner's Save &
+ * publish, and the version history on the form's own page. A second answer
+ * would be a second chance to promote a design the check never saw.
+ *
+ * Pure, and separate from the route, so the refusal can be exercised on real
+ * node maps rather than through a mocked Admin SDK — the property under test
+ * is which trees it says no to, not how a 422 is serialized.
+ *
+ * @param options.form  the STORED form document. `routing` and
+ *                      `consentFieldName` are what the check reads; the
+ *                      stored `fields` are the previous design's output, not
+ *                      a contract the new one owes anything to — except the
+ *                      contact-field mappings drawn on them, which are
+ *                      carried across by field name (AGL-2601).
+ * @param options.storedNodes the version document's `nodes` in any stored
+ *                      form — a besigner save writes them compressed.
+ * @param options.formsOnForSite whether Forms runs on the site (AGL-3029):
+ *                      `false` refuses the promotion with the contract's own
+ *                      sentence, whatever the design.
+ */
+export declare function resolveFormPromotion(options: {
+    formId: string;
+    form: Record<string, unknown> | null | undefined;
+    storedNodes: unknown;
+    formsOnForSite?: boolean;
+}): FormPromotionWrite | FormPromotionRefusal;
+export default resolveFormPromotion;

package/src/lib/server/form-promotion.js

@@ -0,0 +1,133 @@
+/**
+ * @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.
+ */ import { canvasTreeToDefinition, carryContactFieldMappings, checkFormContract, decodeStoredNodes, formContractIsSatisfied, formFieldDeclsFromNodes, FORMS_OFF_FOR_SITE_VIOLATION } from "@aglyn/aglyn/server";
+/** The canvas id a form's own node carries. */ const FORM_COMPONENT_ID = 'form';
+/** Whether this answer is the refusal. */ export function isFormPromotionRefusal(result) {
+    return result.status !== undefined;
+}
+/**
+ * WHAT A PROMOTION WOULD WRITE, OR WHY IT MUST NOT HAPPEN.
+ *
+ * Promoting a form is not "copy the drawing onto the parent". A reusable
+ * component's promotion is exactly that, because a component is only ever
+ * DRAWN — the worst a bad one does is make a page ugly, and the page still
+ * renders. A form is drawn AND it is a contract: `/api/forms/submit` keys
+ * submissions on the id the form node carries, reads marketing consent out of
+ * a field the document 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 every break is silent — the form renders, the
+ * visitor submits, the row lands, and the thing the merchant believed they
+ * were collecting is not there.
+ *
+ * So this decides, before any write exists to undo, and it decides in one
+ * place because there are two ways to reach a promotion: the besigner's Save &
+ * publish, and the version history on the form's own page. A second answer
+ * would be a second chance to promote a design the check never saw.
+ *
+ * Pure, and separate from the route, so the refusal can be exercised on real
+ * node maps rather than through a mocked Admin SDK — the property under test
+ * is which trees it says no to, not how a 422 is serialized.
+ *
+ * @param options.form  the STORED form document. `routing` and
+ *                      `consentFieldName` are what the check reads; the
+ *                      stored `fields` are the previous design's output, not
+ *                      a contract the new one owes anything to — except the
+ *                      contact-field mappings drawn on them, which are
+ *                      carried across by field name (AGL-2601).
+ * @param options.storedNodes the version document's `nodes` in any stored
+ *                      form — a besigner save writes them compressed.
+ * @param options.formsOnForSite whether Forms runs on the site (AGL-3029):
+ *                      `false` refuses the promotion with the contract's own
+ *                      sentence, whatever the design.
+ */ export function resolveFormPromotion(options) {
+    const { formId, form, storedNodes } = options;
+    if (options.formsOnForSite === false) {
+        return {
+            status: 422,
+            body: {
+                error: FORMS_OFF_FOR_SITE_VIOLATION.message,
+                violations: [
+                    FORMS_OFF_FOR_SITE_VIOLATION
+                ]
+            }
+        };
+    }
+    const decoded = decodeStoredNodes(storedNodes);
+    if (!decoded || !Object.keys(decoded).length) {
+        return {
+            status: 422,
+            body: {
+                error: 'That version holds no design. Open it in the besigner and save ' + 'once before publishing it.'
+            }
+        };
+    }
+    // Unwrap the synthetic canvas root: a placed form grafts from `rootId`, so
+    // publishing the wrapper would put an always-empty container around every
+    // instance (AGL-680).
+    const definition = canvasTreeToDefinition(decoded);
+    if (definition.ambiguousRoot) {
+        return {
+            status: 422,
+            body: {
+                error: 'A form needs a single top-level element. Wrap what you have in ' + 'one container, save, then publish.'
+            }
+        };
+    }
+    const nodes = definition.nodes;
+    const formNodeId = Object.keys(nodes).find((nodeId)=>{
+        var _nodes_nodeId;
+        return ((_nodes_nodeId = nodes[nodeId]) == null ? void 0 : _nodes_nodeId.componentId) === FORM_COMPONENT_ID;
+    });
+    const violations = checkFormContract({
+        form: form,
+        formId,
+        nodes: nodes,
+        formNodeId: formNodeId
+    });
+    if (!formContractIsSatisfied(violations)) {
+        return {
+            status: 422,
+            body: {
+                // The headline names the CONSEQUENCE; the violations name what to fix.
+                error: 'This version would stop the submissions arriving',
+                violations
+            }
+        };
+    }
+    return {
+        rootId: definition.rootId,
+        nodes,
+        /*
+     * The DECLARATION publishes with the DESIGN.
+     *
+     * `fields` is what the submit route validates against and what the form's
+     * consent-field picker offers; `nodes` is what the author drew. Writing
+     * one without the other is how they drift, and the drift is exactly what
+     * the check above just refused to ship — so the two go out in a single
+     * write, derived from the same tree.
+     *
+     * `checkFormContract` reports `form-node-missing` when there is no form
+     * node, so reaching here means this id resolved.
+     *
+     * Where each field SAVES TO is not drawn on the canvas — it is edited on
+     * the form's page — so it is carried from the stored declaration by
+     * field name, or every publish would unmap every field (AGL-2601).
+     */ fields: carryContactFieldMappings(form == null ? void 0 : form['fields'], formFieldDeclsFromNodes(nodes, formNodeId))
+    };
+}
+export default resolveFormPromotion;
+
+//# sourceMappingURL=form-promotion.js.map

package/src/lib/server/form-promotion.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/forms/src/lib/server/form-promotion.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\nimport {\n  canvasTreeToDefinition,\n  carryContactFieldMappings,\n  checkFormContract,\n  decodeStoredNodes,\n  formContractIsSatisfied,\n  formFieldDeclsFromNodes,\n  FORMS_OFF_FOR_SITE_VIOLATION,\n  type FormContractViolation,\n  type FormFieldDecl,\n  type NodeId,\n} from '@aglyn/aglyn/server'\n\n/** The canvas id a form's own node carries. */\nconst FORM_COMPONENT_ID = 'form'\n\n/** A promotion that must not happen, and what to tell the author. */\nexport interface FormPromotionRefusal {\n  status: number\n  body: {\n    error: string\n    /**\n     * The contract violations, when that is what refused it.\n     *\n     * The pure module's own shape, so a caller renders the same sentences the\n     * besigner does without either side parsing prose. Absent on the two\n     * refusals that are about the CANVAS rather than the contract.\n     */\n    violations?: FormContractViolation[]\n  }\n}\n\n/** Exactly the fields a promotion writes onto the form document. */\nexport interface FormPromotionWrite {\n  rootId?: string\n  nodes: Record<string, any>\n  fields: FormFieldDecl[]\n}\n\n/** Whether this answer is the refusal. */\nexport function isFormPromotionRefusal(\n  result: FormPromotionWrite | FormPromotionRefusal,\n): result is FormPromotionRefusal {\n  return (result as FormPromotionRefusal).status !== undefined\n}\n\n/**\n * WHAT A PROMOTION WOULD WRITE, OR WHY IT MUST NOT HAPPEN.\n *\n * Promoting a form is not \"copy the drawing onto the parent\". A reusable\n * component's promotion is exactly that, because a component is only ever\n * DRAWN — the worst a bad one does is make a page ugly, and the page still\n * renders. A form is drawn AND it is a contract: `/api/forms/submit` keys\n * submissions on the id the form node carries, reads marketing consent out of\n * a field the document NAMES, and creates a lead from an address it expects to\n * find. Every one of those couplings is resolved by NAME at submit time, so\n * the design can break them, and every break is silent — the form renders, the\n * visitor submits, the row lands, and the thing the merchant believed they\n * were collecting is not there.\n *\n * So this decides, before any write exists to undo, and it decides in one\n * place because there are two ways to reach a promotion: the besigner's Save &\n * publish, and the version history on the form's own page. A second answer\n * would be a second chance to promote a design the check never saw.\n *\n * Pure, and separate from the route, so the refusal can be exercised on real\n * node maps rather than through a mocked Admin SDK — the property under test\n * is which trees it says no to, not how a 422 is serialized.\n *\n * @param options.form  the STORED form document. `routing` and\n *                      `consentFieldName` are what the check reads; the\n *                      stored `fields` are the previous design's output, not\n *                      a contract the new one owes anything to — except the\n *                      contact-field mappings drawn on them, which are\n *                      carried across by field name (AGL-2601).\n * @param options.storedNodes the version document's `nodes` in any stored\n *                      form — a besigner save writes them compressed.\n * @param options.formsOnForSite whether Forms runs on the site (AGL-3029):\n *                      `false` refuses the promotion with the contract's own\n *                      sentence, whatever the design.\n */\nexport function resolveFormPromotion(options: {\n  formId: string\n  form: Record<string, unknown> | null | undefined\n  storedNodes: unknown\n  formsOnForSite?: boolean\n}): FormPromotionWrite | FormPromotionRefusal {\n  const { formId, form, storedNodes } = options\n  if (options.formsOnForSite === false) {\n    return {\n      status: 422,\n      body: {\n        error: FORMS_OFF_FOR_SITE_VIOLATION.message,\n        violations: [FORMS_OFF_FOR_SITE_VIOLATION],\n      },\n    }\n  }\n  const decoded = decodeStoredNodes<Record<string, any>>(storedNodes)\n  if (!decoded || !Object.keys(decoded).length) {\n    return {\n      status: 422,\n      body: {\n        error:\n          'That version holds no design. Open it in the besigner and save ' +\n          'once before publishing it.',\n      },\n    }\n  }\n  // Unwrap the synthetic canvas root: a placed form grafts from `rootId`, so\n  // publishing the wrapper would put an always-empty container around every\n  // instance (AGL-680).\n  const definition = canvasTreeToDefinition(decoded)\n  if (definition.ambiguousRoot) {\n    return {\n      status: 422,\n      body: {\n        error:\n          'A form needs a single top-level element. Wrap what you have in ' +\n          'one container, save, then publish.',\n      },\n    }\n  }\n  const nodes = definition.nodes as Record<string, any>\n  const formNodeId = Object.keys(nodes).find(\n    (nodeId) => nodes[nodeId]?.componentId === FORM_COMPONENT_ID,\n  )\n  const violations = checkFormContract({\n    form: form as never,\n    formId,\n    nodes: nodes as never,\n    formNodeId: formNodeId as NodeId | undefined,\n  })\n  if (!formContractIsSatisfied(violations)) {\n    return {\n      status: 422,\n      body: {\n        // The headline names the CONSEQUENCE; the violations name what to fix.\n        error: 'This version would stop the submissions arriving',\n        violations,\n      },\n    }\n  }\n  return {\n    rootId: definition.rootId,\n    nodes,\n    /*\n     * The DECLARATION publishes with the DESIGN.\n     *\n     * `fields` is what the submit route validates against and what the form's\n     * consent-field picker offers; `nodes` is what the author drew. Writing\n     * one without the other is how they drift, and the drift is exactly what\n     * the check above just refused to ship — so the two go out in a single\n     * write, derived from the same tree.\n     *\n     * `checkFormContract` reports `form-node-missing` when there is no form\n     * node, so reaching here means this id resolved.\n     *\n     * Where each field SAVES TO is not drawn on the canvas — it is edited on\n     * the form's page — so it is carried from the stored declaration by\n     * field name, or every publish would unmap every field (AGL-2601).\n     */\n    fields: carryContactFieldMappings(\n      form?.['fields'] as FormFieldDecl[] | undefined,\n      formFieldDeclsFromNodes(nodes as never, formNodeId as NodeId),\n    ),\n  }\n}\n\nexport default resolveFormPromotion\n"],"names":["canvasTreeToDefinition","carryContactFieldMappings","checkFormContract","decodeStoredNodes","formContractIsSatisfied","formFieldDeclsFromNodes","FORMS_OFF_FOR_SITE_VIOLATION","FORM_COMPONENT_ID","isFormPromotionRefusal","result","status","undefined","resolveFormPromotion","options","formId","form","storedNodes","formsOnForSite","body","error","message","violations","decoded","Object","keys","length","definition","ambiguousRoot","nodes","formNodeId","find","nodeId","componentId","rootId","fields"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,sBAAsB,EACtBC,yBAAyB,EACzBC,iBAAiB,EACjBC,iBAAiB,EACjBC,uBAAuB,EACvBC,uBAAuB,EACvBC,4BAA4B,QAIvB,sBAAqB;AAE5B,6CAA6C,GAC7C,MAAMC,oBAAoB;AAyB1B,wCAAwC,GACxC,OAAO,SAASC,uBACdC,MAAiD;IAEjD,OAAO,AAACA,OAAgCC,MAAM,KAAKC;AACrD;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkCC,GACD,OAAO,SAASC,qBAAqBC,OAKpC;IACC,MAAM,EAAEC,MAAM,EAAEC,IAAI,EAAEC,WAAW,EAAE,GAAGH;IACtC,IAAIA,QAAQI,cAAc,KAAK,OAAO;QACpC,OAAO;YACLP,QAAQ;YACRQ,MAAM;gBACJC,OAAOb,6BAA6Bc,OAAO;gBAC3CC,YAAY;oBAACf;iBAA6B;YAC5C;QACF;IACF;IACA,MAAMgB,UAAUnB,kBAAuCa;IACvD,IAAI,CAACM,WAAW,CAACC,OAAOC,IAAI,CAACF,SAASG,MAAM,EAAE;QAC5C,OAAO;YACLf,QAAQ;YACRQ,MAAM;gBACJC,OACE,oEACA;YACJ;QACF;IACF;IACA,2EAA2E;IAC3E,0EAA0E;IAC1E,sBAAsB;IACtB,MAAMO,aAAa1B,uBAAuBsB;IAC1C,IAAII,WAAWC,aAAa,EAAE;QAC5B,OAAO;YACLjB,QAAQ;YACRQ,MAAM;gBACJC,OACE,oEACA;YACJ;QACF;IACF;IACA,MAAMS,QAAQF,WAAWE,KAAK;IAC9B,MAAMC,aAAaN,OAAOC,IAAI,CAACI,OAAOE,IAAI,CACxC,CAACC;YAAWH;eAAAA,EAAAA,gBAAAA,KAAK,CAACG,OAAO,qBAAbH,cAAeI,WAAW,MAAKzB;;IAE7C,MAAMc,aAAanB,kBAAkB;QACnCa,MAAMA;QACND;QACAc,OAAOA;QACPC,YAAYA;IACd;IACA,IAAI,CAACzB,wBAAwBiB,aAAa;QACxC,OAAO;YACLX,QAAQ;YACRQ,MAAM;gBACJ,uEAAuE;gBACvEC,OAAO;gBACPE;YACF;QACF;IACF;IACA,OAAO;QACLY,QAAQP,WAAWO,MAAM;QACzBL;QACA;;;;;;;;;;;;;;;KAeC,GACDM,QAAQjC,0BACNc,wBAAAA,IAAM,CAAC,SAAS,EAChBV,wBAAwBuB,OAAgBC;IAE5C;AACF;AAEA,eAAejB,qBAAoB"}

package/src/lib/server/form-publish-announce.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @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.
+ */
+import { type UsageSources } from '@aglyn/tenant-data-admin/server/live-page-usage';
+/**
+ * Every live screen whose rendered output contains the form `formId`, however
+ * indirectly.
+ *
+ * The form twin of {@link screenIdsUsingComponentDeep}, and the same walk for
+ * the same reason: a placed form is found by SEARCHING node trees, not by
+ * matching a pointer, and it can sit on a screen, inside page chrome, or
+ * inside a reusable component that a third component nests. Publishing a form
+ * changes every page that renders it, so anything this misses keeps serving
+ * the old fields for the whole revalidate window while the editor reports that
+ * the live sites now serve the new design.
+ *
+ * The first level is the only thing that differs from the component walk: a
+ * document uses a form by PLACING it. After that the fan-out is identical, so
+ * it is delegated rather than restated — a component that holds the form is
+ * reached by whatever reaches that component, and a layout by whatever renders
+ * inside it.
+ *
+ * Pure, and separate from the Firestore read, so the closure is testable
+ * without a database. Cycle-safe by delegation: both walks it defers to bound
+ * themselves.
+ */
+export declare function screenIdsUsingFormDeep(formId: string, sources: UsageSources): string[];
+/**
+ * Drop the cached pages that place `formId`, after its design was published.
+ *
+ * The plugin knows WHICH pages — the ones whose node trees place the form,
+ * found by {@link screenIdsUsingFormDeep} over the site's screens, layouts and
+ * components — and the app knows how to drop one on every address the site
+ * answers at, so the addresses go through the platform's site cache
+ * (`dropPluginSiteCache`, narrowed by `paths`).
+ *
+ * BEST EFFORT, ALWAYS. The publish has already succeeded by the time this
+ * runs, so a failed cache hint must never make it look failed: every failure
+ * resolves, and the render cache's TTL stays underneath as the backstop. A
+ * scan the bound truncated drops the whole site instead, because a prefix of
+ * the site would report a publish while leaving placed pages stale.
+ */
+export declare function announceFormPublish(options: {
+    firestore: FirebaseFirestore.Firestore;
+    hostId: string;
+    formId: string;
+}): Promise<{
+    revalidated: number;
+    screenIds: string[];
+}>;