@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/jobs/ai-job-form-step.d.ts

@@ -0,0 +1,250 @@
+/**
+ * @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 FormFieldDecl, type FormRouting } from '@aglyn/aglyn/app-utils/forms';
+import { type NodesMap } from '@aglyn/aglyn/types/nodes';
+import { duplicateResource } from '@aglyn/tenant-data-admin/server/duplicate-resource';
+import type { AiJob, AiJobPlan } from '../model/ai-jobs.types';
+import { type AiSiteSubmissions } from '../model/ai-site-job';
+import { type AiValidatedTree } from '../runtime/ai-doctrine';
+import type { AiDoctrineViolation } from '../runtime/ai-doctrine-validators';
+import type { AiSystemBlock, AiTool } from '../runtime/ai-runtime';
+import { readSiteInventory } from '../runtime/site-inventory';
+import { type AiJobAdmission } from './ai-job-admission';
+import type { AiJobStepRunner } from './ai-job-text-step';
+/**
+ * The form step (AGL-2913): the generation step of a `form` job, run once a
+ * member confirmed the job's plan.
+ *
+ * A form is two halves that must agree for its submissions to arrive: the
+ * DESIGN a visitor fills in (`rootId`, `nodes`) and the DECLARATION the submit
+ * route reads (`fields`, `consentFieldName`, `routing`). `checkFormContract`
+ * is the rule that holds them together when a form is published. So the model
+ * writes only the design, through `runValidatedGeneration('form', …)`, and
+ * everything else is derived from it with the functions the publish paths
+ * use:
+ *
+ *  - `fields` is `formFieldDeclsFromNodes` over the design;
+ *  - a form that can yield an email address gets the platform's marketing
+ *    consent field (`MARKETING_CONSENT_FORM_FIELD`, the Forms editor preset's own
+ *    props) in place of any consent-like field the model drew, named as its
+ *    `consentFieldName`;
+ *  - `routing` is `{ lead: true }` when the answer proposes a lead, and
+ *    nothing otherwise. The stored routing has no place for an email list,
+ *    so a list proposal leaves the form on the Inbox and says, in the output's
+ *    `note`, how to enroll the people who tick consent — naming a list only
+ *    when the brief named one. The step reads no list, contact, CRM record or
+ *    submission, and sends none.
+ *
+ * The design is then stamped the way the Forms page's Create stamps one — the
+ * form node bound to the new form's id, a canvas root above it — and
+ * `checkFormContract` runs on it through `extend`, beside the doctrine's own
+ * checks, so a design the contract would refuse at publish is asked for again
+ * with the violation named.
+ *
+ * The form lands as a new draft (`ai-job-drafts.ts`) that no page places and
+ * nothing promotes. A plan that starts from a copy of a form the site has gets
+ * that copy, through the platform's duplicate module, and nothing generated —
+ * and because that path reaches no model, `extend` never runs on it, so the
+ * step asks `checkFormContract` of the stored copy itself before it reports
+ * one (AGL-3024). A copy still bound to the form it was copied from is a
+ * failure, never an output.
+ *
+ * Like the other generation steps, it runs on the job beat, never at an inline
+ * door: it registers the least time its lookup rounds, its answer and its
+ * re-ask need (AGL-3035), and runs without extended thinking under the routing
+ * table's ceiling for a form, which is the doctrine's own.
+ */
+/**
+ * The longest answer a form may run to: the routing table's `job.form`
+ * ceiling, which holds the largest form the output budget admits
+ * (`ai-job-form-step.spec.ts` measures it) and is the doctrine's ceiling for
+ * the form kind.
+ */
+export declare const AI_JOB_FORM_MAX_TOKENS: number;
+/**
+ * The form step's time (AGL-3035, AGL-3036): its two inventory-lookup rounds,
+ * its answer and its re-ask at that ceiling on the tier `job.form` is served
+ * from, fitted to what a beat can give a step.
+ */
+export declare const AI_JOB_FORM_STEP_BUDGET: import("./ai-job-budget").AiJobStepBudget;
+/** The least time one form step needs before it starts. */
+export declare const AI_JOB_FORM_STEP_MINIMUM_MS: number;
+/** A form's name when the plan names none. */
+export declare const AI_JOB_FORM_DEFAULT_NAME = "New form";
+/** Where a proposal routes a form's submissions. */
+export declare const AI_FORM_ROUTING_KINDS: readonly ["inbox", "list", "lead"];
+export type AiFormRoutingKind = (typeof AI_FORM_ROUTING_KINDS)[number];
+/** The most things a note says the brief asked for and a form cannot collect. */
+export declare const AI_FORM_CANNOT_COLLECT_MAX = 3;
+/** The node id the platform's consent field takes in a generated design. */
+export declare const AI_FORM_CONSENT_NODE_ID = "marketingConsentField";
+/** The form step's own instructions, cached after the doctrine. */
+export declare const AI_JOB_FORM_INSTRUCTIONS: readonly AiSystemBlock[];
+/**
+ * The doctrine's form tree tool, with the two things a design cannot say: the
+ * routing it proposes and what the brief asked for that no field can collect.
+ * Structured fields only, so the step writes every sentence a person reads.
+ */
+export declare const AI_JOB_FORM_TOOL: AiTool;
+/** The routing and the gaps an answer proposes, read defensively. */
+export interface AiFormAnswer {
+    routing: {
+        kind: AiFormRoutingKind;
+        list: string | null;
+    };
+    cannotCollect: string[];
+}
+/**
+ * What the person already decided about this form, where they were asked
+ * (AGL-2918).
+ *
+ * Only the guided start asks, so only a scaffold's form unit carries one.
+ * Whether a submission is a note to read or a lead to chase is a fact about
+ * how a business runs, not something readable off a brief, so an answer here
+ * BINDS the routing instead of joining the evidence the model weighs: a
+ * person who said "the Inbox" and got a form filing leads would have been
+ * asked a question for nothing.
+ */
+export interface AiFormDecisions {
+    /** Where submissions go; `null` where nobody was asked. */
+    submissions: AiSiteSubmissions | null;
+}
+/**
+ * An answer's routing and gaps: an unknown kind is the Inbox, and the rest is
+ * trimmed and capped. Where the person was asked where submissions go, their
+ * answer replaces the model's proposal — the whole of the difference a
+ * question makes.
+ */
+export declare function parseAiFormAnswer(answer: Record<string, unknown>, decisions?: AiFormDecisions): AiFormAnswer;
+/** A generated form as its draft is written: the stamped design and what it declares. */
+export interface AiFormDraft {
+    /** The design as the Forms page's Create stores one: a canvas root above the bound form. */
+    nodes: NodesMap;
+    rootId: string;
+    formNodeId: string;
+    fields: FormFieldDecl[];
+    consentFieldName: string | null;
+    routing: FormRouting | null;
+    answer: AiFormAnswer;
+}
+/**
+ * The draft a validated design and its answer make: the form node bound to
+ * `formId` and captioned `name`, no dataset binding, the platform's consent
+ * field when the fields can yield an email address, the canvas root above,
+ * and the declaration read off the result. Pure; the input tree is not
+ * changed.
+ */
+export declare function aiFormDraft(tree: Pick<AiValidatedTree, 'rootId' | 'nodes'>, answer: Record<string, unknown>, identity: {
+    formId: string;
+    name: string;
+    decisions?: AiFormDecisions;
+}): AiFormDraft;
+/**
+ * What a draft would break once published, as building-rule violations
+ * (rule 3: a form is built with its fields, validation, consent and routing
+ * together): the form contract's findings, a form with no field, and a list
+ * proposal on a form that asks for no email address. Offending nodes are
+ * named by the ids the model wrote.
+ */
+export declare function aiFormDraftViolations(draft: AiFormDraft, formId: string, sourceIds: Readonly<Record<string, string>>): AiDoctrineViolation[];
+/**
+ * The door's check for `extend`, and the draft each admitted tree made: the
+ * tree a generation returns is the object its last check saw, so the step
+ * writes exactly the draft the contract passed.
+ */
+export declare function aiFormDraftCheck(identity: {
+    formId: string;
+    name: string;
+    decisions?: AiFormDecisions;
+}): {
+    extend: (tree: AiValidatedTree, answer: Record<string, unknown>) => AiDoctrineViolation[];
+    draftFor: (tree: AiValidatedTree) => AiFormDraft | undefined;
+};
+/**
+ * What a job says when the copy it asked for came back naming the form it
+ * was copied FROM (AGL-3024). The contract's own sentence follows it and
+ * names the consequence; this one names what to do about it.
+ */
+export declare const AI_FORM_COPY_UNBOUND_FAILURE: string;
+/**
+ * Whether the copy the platform just wrote is bound to ITSELF, asked of the
+ * document rather than of the answer — `null` when it is, and the sentence a
+ * person reads when it is not.
+ *
+ * ## Why a step that generated nothing still has something to check
+ *
+ * A "creates X from a copy of Y" plan reaches no model: the copy IS the
+ * output, so there is no answer for the doctrine to refuse and `extend`
+ * never runs. That left the one thing a copy can get wrong unasked. A form's
+ * design names its own form inside itself, and a copy that kept the source's
+ * name files every submission under the source — the console's form page
+ * banners exactly this, and the job reported Done beside it.
+ *
+ * So the check is `checkFormContract`, the SAME function the console's
+ * banner and the promotion route ask, run here on the stored copy. Not a
+ * second predicate shaped like it: a copy this one passed and that one
+ * refused would be a form the job called finished and the console called
+ * broken, which is the state this exists to make impossible.
+ *
+ * Narrowed to `form-id-unbound`, and only that, because it is the one
+ * violation duplication CAUSES. Every other code the contract can report —
+ * an unnamed field, a consent field the design lost — the copy inherited
+ * from a form the site already has and the member chose to copy; refusing
+ * those would be refusing to copy a form they can already see.
+ */
+export declare function aiFormCopyUnboundFailure(firestore: FirebaseFirestore.Firestore, copy: {
+    hostId: string;
+    formId: string;
+}): Promise<string | null>;
+/**
+ * What the person decides next, in words the step writes itself: a lead
+ * routing to keep or switch off, the list a proposal could not store, and what
+ * the brief asked for that a form cannot collect. `null` when there is none.
+ */
+export declare function aiFormOutputNote(answer: AiFormAnswer): string | null;
+/**
+ * The form job as the generation's user turn: the name, who fills the form
+ * in, the brief, and the confirmed plan.
+ *
+ * Who the form is for (AGL-2918) is the answer a contact form's FIELDS turn
+ * on — a trades business asks where the work is, a practice asks what the
+ * appointment is about — and it is not something a brief about a whole site
+ * says in a place the form can find. It rides here, in the turn, because it
+ * is one site's own words.
+ *
+ * Where submissions go rides here too, and it is NOT a hint: the step binds
+ * the routing to it whatever the model answers. It is stated so the model
+ * does not spend its answer proposing something that will be replaced, and
+ * so a form told its submissions are leads asks for the address that makes
+ * one.
+ */
+export declare function aiJobFormPrompt(job: Pick<AiJob, 'brief'>, plan: AiJobPlan | null, name: string, context?: {
+    audience?: string;
+    submissions?: AiSiteSubmissions | null;
+}): string;
+/** A form job is admitted for a site of the job's own org whose plan has forms, with a form to spare. */
+export declare const aiFormJobAdmission: AiJobAdmission;
+export interface AiJobFormStepDeps {
+    /** The inventory reader; specs hand in a fake. */
+    readInventory?: typeof readSiteInventory;
+    /** The platform's duplicate module, for a plan that starts from a copy. */
+    duplicate?: typeof duplicateResource;
+}
+export declare function createAiJobFormStep(deps?: AiJobFormStepDeps): AiJobStepRunner;
+export declare const runAiJobFormStep: AiJobStepRunner;
+/** Registers the form step and the check a form job passes before it is created or resumed. */
+export declare function registerAiFormJob(): void;