@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/runtime/ai-doctrine-validators.d.ts

@@ -0,0 +1,720 @@
+/**
+ * @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 AiBuildPlan } from '../model/ai-build-plan';
+import { type AiPlanCapabilities } from '../model/ai-plan-capabilities';
+import type { AiSiteInventory } from '../model/ai-site-inventory';
+import { type AiNodeTreeContext, type AiNodeTreeResult } from './ai-node-tree';
+import { type AiBudgetMetric, type AiLoadEstimate, type AiOutputKind } from './ai-palette';
+/**
+ * The building doctrine's validators (AGL-2935): the rules a generated
+ * document is held to, each checked by code rather than asked of a prompt.
+ *
+ * A generator's system prompt carries the doctrine (`ai-doctrine.ts`), and a
+ * model mostly follows it. "Mostly" is what these are for. Every tree and
+ * every plan passes through them inside `runValidatedGeneration`; a finding
+ * is a VIOLATION that names its rule and says, in a sentence a customer can
+ * read, what was refused and what to do instead. The runtime re-asks the
+ * model once with the findings, and stops for a person when the second
+ * answer still breaks one.
+ *
+ * Trees are checked AFTER `validateAiNodeTree` (AGL-2905) has admitted them,
+ * never instead of it: the palette validator decides what may be stored at
+ * all, and these decide whether it was built the way a careful author would
+ * build it. Plans are checked against the site inventory, which is where
+ * "reuse before create" becomes checkable.
+ *
+ * Rule 17 is a MEASUREMENT, in the platform's existing units: the stored
+ * node map in the bytes the save counts (`nodeMapBytes`), images at the size
+ * the media library recorded, an email's HTML as the send path renders it,
+ * and a page's load on top of the page weight the platform already measured.
+ * Nothing here invents a second measure of a page.
+ */
+export type AiDoctrineRuleNumber = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17;
+/** Each rule's title, in the words the proposal and the docs page use. */
+export declare const AI_DOCTRINE_RULES: Readonly<Record<AiDoctrineRuleNumber, string>>;
+export declare const AI_DOCTRINE_RULE_NUMBERS: AiDoctrineRuleNumber[];
+export interface AiDoctrineViolation {
+    /**
+     * The rule broken; `null` when the answer could not be read as the output
+     * at all, or asks for what its job does not build rather than breaking a
+     * building rule.
+     */
+    rule: AiDoctrineRuleNumber | null;
+    /** Stable per finding, for specs and logs. */
+    code: string;
+    /** One customer-safe sentence: what was refused and what to do instead. */
+    message: string;
+    /** What the model is told beyond `message`, when the validator's own words say more. */
+    detail?: string;
+    /** Offending nodes, by the ids of the tree that was checked. */
+    nodeIds?: string[];
+    /** Offending plan entries or answer fields, as `screens[1].sections[2]`. */
+    paths?: string[];
+    /** Rule 17: the measured figure against its budget. */
+    figure?: {
+        metric: AiBudgetMetric;
+        value: number;
+        budget: number;
+    };
+}
+/** A violation as one line: the rule's number and title, then its sentence. */
+export declare function aiDoctrineViolationText(violation: AiDoctrineViolation): string;
+/** Who the copy is framed for; agency and enterprise copy holds to the judgment-word rule. */
+export type AiCopyFraming = 'agency' | 'enterprise' | null;
+export interface AiDoctrineNode {
+    componentId: string;
+    props?: Record<string, unknown>;
+    sx?: Record<string, unknown>;
+    nodes?: string[];
+}
+/** A validated flat node map, as `validateAiNodeTree` returns it. */
+export interface AiDoctrineTree {
+    rootId: string;
+    nodes: Record<string, AiDoctrineNode>;
+}
+/** What a library asset records about itself, for the image weight. */
+export interface AiAssetFacts {
+    sizeBytes?: number;
+    width?: number;
+    height?: number;
+}
+export interface AiDoctrineTreeContext extends AiNodeTreeContext {
+    /** The brand an email is held to: palette path → color, and the families. */
+    brand?: {
+        colors: Record<string, string>;
+        fonts: string[];
+    } | null;
+    /** Placed library assets by media id. */
+    assets?: Record<string, AiAssetFacts>;
+    /** The plan named a third-party embed the brief asked for, and its cost. */
+    allowEmbeds?: boolean;
+    framing?: AiCopyFraming;
+    /**
+     * Whether the workspace keeps reusable components and saved forms
+     * (AGL-3030). `false` builds inline, the one way such a workspace can: a
+     * form is a Form holding its fields, and a repeated block is drawn where it
+     * repeats. Absent is `true`, the doctrine whole.
+     */
+    reusableComponents?: boolean;
+    /**
+     * The site's home screens, by id (AGL-3056): the screen a link falls back
+     * to when the site has none for what it promises. Absent: none is known.
+     */
+    homeScreenIds?: readonly string[];
+    /**
+     * The node as the model wrote it, by the id the checked tree gives it
+     * (AGL-3078), for a tree that was stored before it is checked: a page
+     * section is checked as part of the page, whose props the palette validator
+     * has already read, and a value it could not read is absent there. Absent,
+     * the tree the check is given is what the model wrote.
+     */
+    writtenNode?: (id: string) => unknown;
+    /**
+     * The page's sections by their names in its plan, in order, where the tree
+     * is a page a plan lays out (AGL-3097). A Button or a Screen Link may then go
+     * to one of them, by `scrollTo` naming it or an `href` fragment its name's
+     * words make up, which the page step writes as the platform's Scroll to
+     * element interaction. Absent: a link goes only where its `screenId` or
+     * `href` says.
+     */
+    pageSections?: readonly string[];
+    /**
+     * The section roots of the page, by id, where the tree checked is the page as
+     * the page step stores it (AGL-3097): a link there that carries a Scroll to
+     * element interaction to one of them, built or still to come, goes there.
+     * Only a stored page is given them. The palette validator drops every
+     * interaction a model writes before anything is stored, and an answer's own
+     * are never read.
+     */
+    scrollTargetIds?: readonly string[];
+}
+/** One node of a walk: its id, its depth, and its ancestors' ids from the root down. */
+export interface Visit {
+    id: string;
+    node: AiDoctrineNode;
+    depth: number;
+    ancestors: string[];
+}
+/**
+ * Every reachable node in document order, each once. Exported for a door's
+ * own checks (`extend`), which read a tree the way these detectors do.
+ */
+export declare function walkTree(tree: AiDoctrineTree): Visit[];
+/** Below this, a repeat is a row of buttons, not a block worth a component. */
+export declare const AI_REPEAT_MIN_NODES = 3;
+/** Rule 1: a block on one page this many times is a component. */
+export declare const AI_REPEAT_MIN_COUNT = 3;
+/** Rule 1 across pages: a block this large on two pages is a component. */
+export declare const AI_REPEAT_ACROSS_PAGES_MIN_NODES = 5;
+/** Rule 8: a hand-typed list this long is data. */
+export declare const AI_TYPED_LIST_MIN_ITEMS = 8;
+/**
+ * Rule 1. A block repeated on one page, or a block this page shares with
+ * another page generated beside it, is one component placed as instances.
+ *
+ * A workspace that keeps no reusable components can place no instance, so
+ * there a repeated block is drawn where it repeats, and nothing is refused.
+ */
+export declare function detectRepeatedSubtrees(tree: AiDoctrineTree, otherPages?: readonly AiDoctrineTree[], context?: Pick<AiDoctrineTreeContext, 'reusableComponents'>): AiDoctrineViolation[];
+/**
+ * How many copies of one repeated thing a document shows, read as
+ * generously as the tree allows (AGL-3024): the largest group of nodes the
+ * shape index calls the same shape — the index rule 1 counts repeats with —
+ * or, where a node's children outnumber that, its fan-out.
+ *
+ * GENEROUS ON PURPOSE. The one caller compares this against a count a plan
+ * promised and speaks only when the count is SHORT, so every reading that
+ * finds more items makes the check quieter, never louder: three cards whose
+ * headings a hero's subtitle happens to match read as four and are let
+ * through, and four cards laid out as two rows of two read as four either by
+ * their shared shape or by the rows' fan-out. What it cannot do is find four
+ * items in a document that holds three of everything.
+ */
+export declare function aiRepeatedItemCount(tree: AiDoctrineTree): number;
+/** Whether a document draws its repeated items from a collection, which fills them at render. */
+export declare function aiBindsRepeatedItems(tree: AiDoctrineTree): boolean;
+/**
+ * The regions a layout is built out of, and how each one is found in a tree
+ * (AGL-3024): the landmark elements it may be written as, and the palette
+ * elements that ARE one wherever they appear.
+ *
+ * A CLOSED vocabulary, because it is what a plan's promise of a region is
+ * checked against: a planner naming a region outside it has promised
+ * something no check can find, which the plan rules refuse rather than let
+ * pass as built.
+ */
+export declare const AI_LAYOUT_REGIONS: {
+    readonly header: {
+        readonly elements: readonly ["header"];
+        readonly componentIds: readonly ["muiAppBar"];
+    };
+    readonly nav: {
+        readonly elements: readonly ["nav"];
+        readonly componentIds: readonly [];
+    };
+    readonly sidebar: {
+        readonly elements: readonly ["aside"];
+        readonly componentIds: readonly [];
+    };
+    readonly main: {
+        readonly elements: readonly ["main"];
+        readonly componentIds: readonly ["layoutSlot"];
+    };
+    readonly footer: {
+        readonly elements: readonly ["footer"];
+        readonly componentIds: readonly [];
+    };
+};
+export type AiLayoutRegion = keyof typeof AI_LAYOUT_REGIONS;
+export declare const AI_LAYOUT_REGION_NAMES: AiLayoutRegion[];
+/**
+ * The region a plan's word names, or `null` for a word the vocabulary does
+ * not hold.
+ *
+ * Read the way a recorded plan writes one. A planner names a region as
+ * `header`, as `layoutSlot:slot` or as `footer:region (firm name, address)`,
+ * so the name is what stands before the first colon, capitals are word
+ * breaks, and a trailing "region" or "area" is filler once the whole name has
+ * been tried: "Sidebar region", "side-bar" and `sidebar:links` are one thing.
+ */
+export declare function aiLayoutRegionOf(word: string): AiLayoutRegion | null;
+/** Every region a built tree carries, by the elements and palette elements it holds. */
+export declare function aiTreeLayoutRegions(tree: AiDoctrineTree): Set<AiLayoutRegion>;
+/**
+ * Rule 2. A page carries no copy of what every page carries: an app bar, or
+ * a header, navigation or footer element near the top of the document. The
+ * header of an article inside the page is the article's, not the site's.
+ */
+export declare function detectLayoutRegions(tree: AiDoctrineTree, outputKind: AiOutputKind): AiDoctrineViolation[];
+/**
+ * Rule 3. A form on a page is a Form bound by id to a form built on the
+ * Forms page — fields, validation, consent and routing kept in one place.
+ * Loose fields, an unbound Form, and fields drawn inside a bound Form (which
+ * the page never renders: the placed form's own design replaces them) are
+ * refused. A form's own design is the one place fields are drawn.
+ *
+ * A workspace that keeps no saved forms (AGL-3030) has no Forms page to build
+ * one on, so there the form IS the page's: an unbound Form holding its Form
+ * Fields, which the site's submit route collects like any other. Loose fields
+ * are still refused, and so is an unbound Form with no field to send.
+ */
+export declare function detectInlineForms(tree: AiDoctrineTree, outputKind: AiOutputKind, context?: Pick<AiDoctrineTreeContext, 'reusableComponents'>): AiDoctrineViolation[];
+/**
+ * Rule 5. Every color, spacing, radius and type size is a theme token. A
+ * color the theme lacks is a theme change for the theme door to draft, not a
+ * value written onto one element.
+ */
+export declare function detectLiteralStyles(tree: AiDoctrineTree, outputKind: AiOutputKind): AiDoctrineViolation[];
+/**
+ * Rule 6. An email is painted with the brand: its colors are the site's
+ * brand colors and its fonts the brand's. A mail client cannot resolve a
+ * theme token, so the brand's own values are what an email may name — and
+ * with no brand recorded, the blocks' own defaults.
+ */
+export declare function detectOffBrandEmail(tree: AiDoctrineTree, outputKind: AiOutputKind, brand: AiDoctrineTreeContext['brand']): AiDoctrineViolation[];
+/**
+ * Rule 8 (tree). A long list typed out item by item is data: bound to a
+ * dataset or a content collection it stays current; typed, it is a copy that
+ * goes stale. Instances of one component filled in side by side are the same
+ * list in a component's clothes, and are counted the same way.
+ *
+ * A list is counted within the Section it sits in, the unit a plan counts a
+ * section's items in (AGL-3061): a page's four practice areas and its four
+ * steps are two short lists that happen to share a card, not one long one,
+ * and a plan that kept them must not build a page this refuses. The same
+ * list split across a section's columns is still one list. A tree with no
+ * Section is one group.
+ */
+export declare function detectTypedData(tree: AiDoctrineTree): AiDoctrineViolation[];
+/**
+ * Rule 9. Images are placed from the media library — an asset, or an empty
+ * slot for the author to fill — never hot-linked from another site, and
+ * every picture carries alt text (or says it is decorative).
+ */
+export declare function detectImageSources(tree: AiDoctrineTree, context?: AiNodeTreeContext): AiDoctrineViolation[];
+/**
+ * A heading's level: the element it renders as, else the variant's own.
+ * Exported for a door's own checks, which read an outline the way rule 11
+ * reads a page's.
+ */
+export declare function aiHeadingLevel(node: AiDoctrineNode): number | null;
+/**
+ * Rule 11. One `main` landmark per document, and a heading outline that
+ * starts at one `h1` and never skips a level. The platform places the one
+ * landmark on the layout's slot, or on a page's root when it has no layout
+ * (`stampDocumentLandmark`); a tree that declares two leaves it to pick the
+ * wrong one. A component, a form or an email is placed inside pages, so it
+ * carries no landmark of its own, and a layout carries no `h1`: every page
+ * placed in it brings its own.
+ */
+export declare function detectDocumentStructure(tree: AiDoctrineTree, outputKind: AiOutputKind): AiDoctrineViolation[];
+/**
+ * Rule 12. Widths follow the theme's breakpoints and the palette's
+ * responsive props — a Container's max width, a Grid's span — never a fixed
+ * pixel or viewport width that holds at one screen size. An email's column
+ * is fixed by the medium, and is exempt.
+ */
+export declare function detectAdHocWidths(tree: AiDoctrineTree, outputKind: AiOutputKind): AiDoctrineViolation[];
+/**
+ * Rule 12, for a Grid (AGL-3055). The palette's Grid is one element in both
+ * roles: a CONTAINER lays its direct Grid children out in columns, and an ITEM
+ * takes a size. The sizes are fractions of the container's columns, so an
+ * item under a Grid that is not a container is sized against nothing, and a
+ * row of them stacks one under another at every width; a size that holds at
+ * every width keeps a phone's columns as narrow as a desktop's; and an `sx`
+ * gap on a container spaces the columns outside the widths the items were
+ * sized by, so the last column wraps onto a row of its own. A live About
+ * page's practice areas were the first: a Grid with no container holding three
+ * items sized "4", one column at every width.
+ *
+ * A Grid that is not a container is told what to do by what it was written as
+ * (AGL-3078), because one sentence does not mend every shape: a live About
+ * page's section was refused twice for rule 12, with a re-ask that only ever
+ * said to make the Grid a container of sized columns.
+ *
+ * - `grid-not-container`: a row that is not a container. A Grid that holds
+ *   sized Grid items, sets a prop only a row reads, or holds two or more
+ *   elements of one shape side by side. The rule's intent: a row of cards is a
+ *   container of sized items.
+ * - `grid-as-stack`: any other Grid that is not a container and sets a prop
+ *   only a container reads, or holds two or more elements without being an
+ *   item: a group that only stacks, such as a heading over its text, or one
+ *   written with a column direction, which a Grid does not have. The re-ask
+ *   offers a Stack or a Box for the group, or a container of sized items.
+ * - `grid-item-outside-container`: a sized Grid item that sits in another
+ *   element, such as a Box inside its container. A container sizes only the
+ *   items directly in it, so the re-ask asks to move the item there. A Box or a
+ *   Stack in a container that holds nothing but sized items is refused through
+ *   its items, not as a child of the container that is no item.
+ * - `grid-container-text`: a Grid whose `container` was written as a value the
+ *   palette validator cannot read as true or false, such as the text "True". The
+ *   re-ask names the value as the fault.
+ * - `grid-item-size`: a container's child that is not a Grid item sized full
+ *   width on a phone, or a container of several whose items never step down
+ *   to columns at a larger width.
+ * - `grid-gap`: a container spaced by an `sx` gap rather than its spacing.
+ *
+ * Each re-ask names the Grid or its items by the model's own ids and says what
+ * to write, in the size format the renderer reads. `written` is the node as
+ * the model wrote it, by an id of `tree`, where that is known: the palette
+ * validator reads a `container` it cannot parse, and a column direction, as
+ * absent, and only what was written can name them.
+ */
+export declare function detectUnresponsiveGrids(tree: AiDoctrineTree, outputKind: AiOutputKind, written?: (id: string) => unknown): AiDoctrineViolation[];
+/** Whether an element is one rule 10 holds to a destination: a Button or a Screen Link. */
+export declare function isAiLinkElement(componentId: unknown): boolean;
+/**
+ * Rule 5, for a link on a colored band (AGL-3056). The doctrine asks for
+ * palette tokens, and a band in `primary.main` holding a Screen Link that
+ * sets no color is two valid tokens: but the link keeps the theme's primary
+ * color, so its words are navy on navy. A live About page's footer was the
+ * first, a "Request a Consultation" link on a primary band. A link or a button
+ * whose words are drawn in the family of the band it sits on is refused, with
+ * a re-ask to inherit the band's contrast text or to set it.
+ */
+export declare function detectInvisibleLinks(tree: AiDoctrineTree, outputKind: AiOutputKind): AiDoctrineViolation[];
+/**
+ * Rule 10, for a link sent where the site has nothing for it (AGL-3056). A
+ * link whose purpose the site has no screen for is left out; it never goes to
+ * a screen that does something else. The site inventory cannot say what each
+ * screen is for, but it can name the one a model falls back to: a live About
+ * page's footer sent "Request a Consultation" to the home screen, because the
+ * site had no consultation screen. So a Screen Link or a Button, outside the
+ * header and the navigation, that links the home screen with words that do
+ * not say home is refused, with a re-ask to link the screen that does what it
+ * says, or to leave the link out.
+ */
+export declare function detectUnrelatedScreenLinks(tree: AiDoctrineTree, outputKind: AiOutputKind, context?: Pick<AiDoctrineTreeContext, 'homeScreenIds'>): AiDoctrineViolation[];
+/**
+ * Rule 10, for a link that goes nowhere (AGL-3072). A Button or a Screen Link
+ * goes where its `screenId` or its `href` says, and those are the only
+ * destinations either element carries: the palette validator keeps a
+ * `screenId` the site has, and an `href` that is a path on the site, an
+ * `https:` address or a binding the caller admitted. Nothing else can stand
+ * in for one. A form is sent by the button the Form draws from its own
+ * `submitLabel`, the elements a page places carry no id an anchor could name
+ * (AGL-2867), and a generated node sets no interaction. So a link with
+ * neither is a dead control: a live About page's hero carried a "Request a
+ * Consultation" button with no destination. It is refused, with a re-ask
+ * naming its words and what it may link.
+ *
+ * On a page a plan lays out (`context.pageSections`), a link may also go to a
+ * section of the same page (AGL-3097). A live hero's re-ask was answered with
+ * "#consultation-form", an anchor to the form the plan places last, and the
+ * page stopped at its first section. A link that names a section, by
+ * `scrollTo` or by a fragment that section's name's words make up, goes
+ * there, and the page step writes the platform's Scroll to element
+ * interaction for it. On a page as stored (`context.scrollTargetIds`), a link
+ * carrying that interaction to one of its section roots goes there. Two
+ * faults get a sentence of their own:
+ *
+ * - `link-fragment`: an `href` fragment that names no section. The palette
+ *   validator drops it, so what the link was written with goes nowhere.
+ * - `scroll-target-unknown`: a `scrollTo` naming no section of the page.
+ *
+ * `written` is the node as the model wrote it and `stored` the node as the
+ * check was given it, each by an id of `tree`.
+ */
+export declare function detectLinksWithoutDestination(tree: AiDoctrineTree, outputKind: AiOutputKind, context?: Pick<AiDoctrineTreeContext, 'pageSections' | 'scrollTargetIds'>, written?: (id: string) => unknown, stored?: (id: string) => unknown): AiDoctrineViolation[];
+/**
+ * Rule 13. The AI writes drafts. An answer that asks for anything to be
+ * published, or to go live, is refused whatever else it got right; nothing
+ * downstream reads such a field, and the refusal is what keeps a future
+ * reader from starting to.
+ */
+export declare function detectPublishIntent(answer: unknown): AiDoctrineViolation[];
+/**
+ * The facts in square brackets copy holds (rule 14), each once whatever its
+ * case, in the order they first appear, as the copy spells them
+ * (AGL-3056): what a member fills in before a draft is published.
+ */
+export declare function aiBracketedFacts(texts: Iterable<string>): string[];
+export interface AiCopySample {
+    /** A node id for a tree, a path for a plan. */
+    at: string;
+    text: string;
+}
+/**
+ * Rule 14. Copy in the site's voice: no lorem ipsum or "your text here"
+ * filler, and — for copy framed for agencies and enterprises — no words that
+ * judge the reader's work as simple or cheap.
+ */
+export declare function detectOffVoiceCopy(samples: readonly AiCopySample[], framing?: AiCopyFraming): AiDoctrineViolation[];
+/** Every piece of copy a tree carries, with the node it sits on. */
+export declare function aiTreeCopy(tree: AiDoctrineTree, context?: AiNodeTreeContext): AiCopySample[];
+/**
+ * The word a line ends on when that word leaves it unfinished (AGL-3072), or
+ * `null`. A line that closes itself, ends on a binding or a bracketed fact the
+ * member fills, or ends on any other word, is finished as far as a check can
+ * tell. Exported for the specs that hold the closed list.
+ */
+export declare function aiDanglingWord(line: string): string | null;
+/**
+ * Rule 14, for a line cut short (AGL-3072). Copy in the site's voice is
+ * finished copy: a heading, a subhead or a body text that ends on an article
+ * or a joining conjunction, or on a word that opens a phrase right after a
+ * comma, with no closing punctuation, reads as a sentence cut off mid-thought.
+ * A live About page's hero subhead ended "…that matter most, with". A closed
+ * list of words, on the lines a reader reads, keeps it deterministic: a
+ * label, a button, a caption and a bracketed fact are never held to it.
+ */
+export declare function detectDanglingWords(tree: AiDoctrineTree): AiDoctrineViolation[];
+/**
+ * Rule 14, for a line cut at its ceiling (AGL-3076). The palette validator
+ * holds copy to a ceiling for its role and cuts what runs past it, and says so
+ * only in its repairs. A cut line is unfinished wherever the cut falls, after
+ * a word or inside one, and a heading style's ceiling of
+ * `AI_TEXT_LIMITS.headline` characters is one the catalog never shows a model:
+ * a live About page's hero subhead, a Typography in the h5 style, was cut at
+ * 120 characters to "…that matter most, with". So a heading, a subhead, a body
+ * line, or a button's or a link's label the validator cut is refused, with a
+ * re-ask naming the ceiling.
+ *
+ * `repairs` are the palette validator's, naming nodes by the ids of the tree
+ * it was given, `written`; `idOf` turns such an id into the id the violation
+ * names.
+ */
+export declare function detectCutLines(repairs: readonly string[], written: Readonly<Record<string, unknown>>, idOf?: (id: string) => string): AiDoctrineViolation[];
+/**
+ * Rule 16. The flattest tree that renders the design: no container that
+ * wraps one other container and adds nothing, no empty containers, no inline
+ * style repeated where a token or a component prop would carry it, no font
+ * beyond the theme's, images lazy below the first, video by poster rather
+ * than autoplay, and no third-party embed the plan did not name.
+ */
+export declare function detectHeavyDocument(tree: AiDoctrineTree, outputKind: AiOutputKind, context?: AiDoctrineTreeContext): AiDoctrineViolation[];
+/**
+ * Rule 16, for an item with nothing in it (AGL-3072). A list item or a card
+ * that holds elements, none of which shows a word, a picture or anything
+ * else, is an empty row or an empty box on the page: a live About page's list
+ * of estate planning services ended on a List Item whose List Item Text had
+ * no words. An item that holds no element at all is `empty-container`'s, and
+ * is not reported twice.
+ */
+export declare function detectEmptyItems(tree: AiDoctrineTree): AiDoctrineViolation[];
+export interface AiOutputScore {
+    nodes: number;
+    /** The stored node map, in the save's own bytes. */
+    bytes: number;
+    /** What the placed library images request, from their recorded sizes. */
+    imageBytes: number;
+    /** Placed images the media library could not size: hot-linked, or no facts supplied. */
+    imagesUnmeasured: number;
+    embeds: number;
+    fontFamilies: number;
+    /** An email's rendered HTML; `null` for every other output. */
+    emailHtmlBytes: number | null;
+}
+/** The rule-17 measurements of one validated tree. */
+export declare function scoreAiOutput(tree: AiDoctrineTree, outputKind: AiOutputKind, context?: AiDoctrineTreeContext): AiOutputScore;
+/**
+ * Rule 17. An output over its kind's budget is refused with the figure, the
+ * budget and the heaviest parts named, so the re-ask knows where to cut.
+ */
+export declare function detectOverBudget(score: AiOutputScore, outputKind: AiOutputKind, tree: AiDoctrineTree, context?: AiDoctrineTreeContext): AiDoctrineViolation[];
+/**
+ * What a first visit to a generated output is estimated to transfer.
+ *
+ * The page half is a MEASUREMENT the platform already holds, not a guess:
+ * `ESTIMATED_PAGE_TRANSFER_BYTES` is the first-party weight a published page
+ * measured at settle, which `check:page-view-rate` holds against the
+ * tenant page budget and the bandwidth meter is priced from. The tenant's
+ * real-user vitals (`web-vitals-rum.ts`) report to analytics per visit and
+ * are not readable for a draft nobody has visited, so they are not a second
+ * source here. On top of that weight go this output's own stored document
+ * and the images it places. A component or a layout reports what it adds to
+ * a page; an email is not a page load and has none.
+ */
+export declare function estimateAiOutputLoad(score: AiOutputScore, outputKind: AiOutputKind): AiLoadEstimate | null;
+/**
+ * A NODE MAP THAT DOES NOT AGREE WITH ITSELF (AGL-3143).
+ *
+ * A flat node map is two halves that have to match: what each node lists
+ * under `nodes`, and what the map holds. A model writing one section in one
+ * pass gets them out of step in two ways, and neither reaches it as
+ * something it can act on.
+ *
+ * An element written but listed by nobody is dropped on the way in, so the
+ * container that should have held it reads as empty and the answer comes
+ * back "an element meant to hold content is empty — remove it, or fill it".
+ * The content is already written; it is one line away from being placed, and
+ * the re-ask does not say so. A live page build was told exactly that of a
+ * card grid whose repeated card it had written and not placed; it answered by
+ * naming four children and writing one.
+ *
+ * Which is the other half: a name listed under `nodes` that the map never
+ * holds. That one is refused, but by the sanitizer under the palette
+ * validator, as `Missing node "card2"` — which the door turns into "the
+ * answer could not be used as a section", with no rule, no node and nothing
+ * to change. It cost that page its last attempt and the build stopped three
+ * sections in, so the page's form — the thing being measured — was never
+ * reached at all.
+ *
+ * Both are read off the tree AS THE MODEL WROTE IT, before the palette
+ * validator drops anything, so a re-ask can quote the node at fault.
+ */
+export declare function detectDisagreeingNodes(input: unknown): AiDoctrineViolation[];
+export interface AiDoctrineTreeReport {
+    ok: boolean;
+    /** The palette validator's result: the tree to store, its repairs and its id map. */
+    tree: Extract<AiNodeTreeResult, {
+        ok: true;
+    }> | null;
+    violations: AiDoctrineViolation[];
+    score: AiOutputScore | null;
+    load: AiLoadEstimate | null;
+}
+/**
+ * The whole check on one emitted tree: the palette validator first, then
+ * every tree rule, then the budget. `otherPages` are the trees generated
+ * beside this one, for the across-pages half of rule 1.
+ */
+export declare function validateAiDoctrineTree(input: unknown, outputKind: AiOutputKind, context?: AiDoctrineTreeContext, otherPages?: readonly AiDoctrineTree[]): AiDoctrineTreeReport;
+/**
+ * Whether two names name the same thing: the same words once filler is
+ * dropped, or every word of a name of two or more words inside the other.
+ */
+export declare function aiNamesMatch(left: string, right: string): boolean;
+/**
+ * Rule 1 (plan): repeated items place a component, and a section two screens
+ * share is one. A workspace that keeps no reusable components draws them in
+ * their sections instead (AGL-3030), and nothing is refused.
+ */
+export declare function detectPlanRepeats(plan: AiBuildPlan, inventory: AiSiteInventory | null, capabilities?: AiPlanCapabilities | null): AiDoctrineViolation[];
+/** The fewest sections of one item, side by side and of one kind, that are one list split apart. */
+export declare const AI_SPLIT_LIST_MIN_SECTIONS = 2;
+/**
+ * Rule 1 (plan): a list is one section whose items repeat (AGL-3071). A
+ * section's `items` counts what it repeats, so two or more sections side by
+ * side that each show one item of the same kind — the same component, or a
+ * name that labels the same kind of item — are one list split apart. A live
+ * Free About page planned "the four areas we practice" as four sections of one
+ * item: none was drawn from the one written-once item a repeated section is
+ * built from, and the four came out in three different shapes. The re-ask
+ * names the sections and gives the one section to plan instead. Where the
+ * workspace keeps reusable components, a list long enough for rule 1 places
+ * one for its item, so the section it gives places one too.
+ *
+ * Sections of several items are never joined: two lists that share a card
+ * are two lists, and rule 8 counts each within its own section (AGL-3061).
+ */
+export declare function detectPlanSplitLists(plan: AiBuildPlan, inventory: AiSiteInventory | null, capabilities?: AiPlanCapabilities | null): AiDoctrineViolation[];
+/**
+ * Rule 2 (plan): every screen declares a layout, no section is a copy of a
+ * layout region, and no section places a layout, which frames a whole screen
+ * (AGL-3040). A site with no layout, where this job may not create one
+ * (AGL-3030), has nothing to declare: its screens name none, and a screen
+ * that names none is not refused there. A screen whose layout is a `new:`
+ * reference the plan never creates is refused here, and only here.
+ */
+export declare function detectPlanLayoutRegions(plan: AiBuildPlan, inventory: AiSiteInventory | null, capabilities?: AiPlanCapabilities | null): AiDoctrineViolation[];
+/**
+ * Rule 3 (plan): a section that collects answers places a form from the Forms
+ * page. A workspace that keeps no saved forms draws the form on the page
+ * (AGL-3030), and nothing is refused.
+ */
+export declare function detectPlanInlineForms(plan: AiBuildPlan, inventory: AiSiteInventory | null, capabilities?: AiPlanCapabilities | null): AiDoctrineViolation[];
+/** Pages sharing one shape this many times are a template applied. */
+export declare const AI_SIMILAR_PAGES_MIN = 3;
+/**
+ * Rule 4 (plan): three or more screens with the same sections share one
+ * template, and a template is what a screen applies, never what one of its
+ * sections places (AGL-3040).
+ */
+export declare function detectUntemplatedSimilarPages(plan: AiBuildPlan, inventory?: AiSiteInventory | null): AiDoctrineViolation[];
+/** Rule 5 (plan): a color value belongs only in a theme change. */
+export declare function detectPlanLiteralColors(plan: AiBuildPlan): AiDoctrineViolation[];
+/** Rule 7 (plan): reuse names real records, and a creation is an exception that says why. */
+export declare function detectCreateBeforeReuse(plan: AiBuildPlan, inventory: AiSiteInventory | null): AiDoctrineViolation[];
+/**
+ * Rule 7 (plan): a plan creates only what the request says this job may
+ * create on this site (AGL-3030) — what the workspace's plan includes, what
+ * the site has room for, and what the job builds itself. One violation a
+ * creation, each saying why and what to do instead.
+ */
+export declare function detectPlanUncreatable(plan: AiBuildPlan, capabilities: AiPlanCapabilities | null): AiDoctrineViolation[];
+/**
+ * Rule 7 (plan): what a plan places, it reuses or it creates (AGL-3040). The
+ * doctrine has a plan refer to what it creates as new:<name>, so a reference
+ * that names no entry of the create list is a creation nothing builds. A page
+ * kept with one stops at its first pass, sending the member to make that
+ * creation by hand, which a workspace that cannot make it never can. Each is
+ * refused with the one re-ask, once a name however often it is placed, and
+ * says what to do on THIS workspace: declare the creation where the job may
+ * make one more of that kind, and otherwise build the page without it, drawn
+ * on the page or placed from what the site has. A screen's layout is rule
+ * 2's (`plan-screen-without-layout`), and is not reported twice.
+ */
+export declare function detectPlanUndeclaredCreations(plan: AiBuildPlan, inventory: AiSiteInventory | null, capabilities?: AiPlanCapabilities | null): AiDoctrineViolation[];
+/**
+ * Rule 8 (plan): long lists are bound, and a list the site already holds is
+ * bound to it. Where this job may not create a dataset (AGL-3030), the way
+ * out the refusal names is a shorter list rather than a dataset it would
+ * only refuse next.
+ */
+export declare function detectPlanTypedData(plan: AiBuildPlan, inventory: AiSiteInventory | null, capabilities?: AiPlanCapabilities | null): AiDoctrineViolation[];
+export declare const AI_SEO_TITLE_MAX = 70;
+export declare const AI_SEO_DESCRIPTION_MAX = 170;
+/** Rule 10 (plan): every screen has a free, well-formed slug, an SEO title and description. */
+export declare function detectMissingNavAndSeo(plan: AiBuildPlan, inventory: AiSiteInventory | null): AiDoctrineViolation[];
+/** Every piece of copy a plan carries, with its path. */
+export declare function aiPlanCopy(plan: AiBuildPlan): AiCopySample[];
+/** Rule 15 (plan): a screen or template like one the site has starts as its duplicate. */
+export declare function detectMissedDuplicate(plan: AiBuildPlan, inventory: AiSiteInventory | null): AiDoctrineViolation[];
+/** What each exchange of a Free page job comes to at its worst, in credits. */
+export interface AiFreePageWorstCase {
+    /** The page plan. */
+    plan: number;
+    /** The one layout a Free plan includes, built first on a site with none (AGL-3031). */
+    layout: number;
+    /** The first section pass, which writes the cached prefix. */
+    firstSection: number;
+    /** Each later section pass, which reads it. */
+    laterSection: number;
+    /** A page's listing. */
+    listing: number;
+}
+/**
+ * The Free taste's wall at its worst (AGL-3030, AGL-3070): each exchange of a
+ * Free page job in credits, every answer at its ceiling, as
+ * `jobs/ai-job-free-page.spec.ts` derives them from the page plan and the
+ * layout generation measured live and the requests as they stand. The spec
+ * fails when a figure it derives moves and this does not, so the section cap
+ * below cannot drift from the proof.
+ */
+export declare const AI_FREE_PAGE_WORST_CASE_CREDITS: Readonly<AiFreePageWorstCase>;
+/**
+ * The most sections a Free job fits in `FREE_AI_TASTE_CREDITS_PER_MONTH` at
+ * its worst: the plan, the layouts it builds first, a listing for each page
+ * and the first section's pass, then as many later passes as the rest pays
+ * for; none when that is already past the wall. A component or a form is never
+ * a Free creation, since rule 7 refuses both on a workspace that keeps no
+ * reusable components, so the wall's proof measures neither.
+ */
+export declare function aiFreePageSectionsWithin(creations: {
+    layouts: number;
+    pages?: number;
+}, credits?: Readonly<AiFreePageWorstCase>): number;
+/**
+ * The Free wall (plan): a plan asks for no more sections than the Free taste
+ * pays for at its worst beside what the job builds first (AGL-3070). A live
+ * Free plan asked for eight sections beside its layout, where the wall's worst
+ * case pays for six, and fit only because every exchange ran under its
+ * ceiling; one that does not runs out of credits with its page half built. The
+ * cap only lowers what a plan may ask for, from the same figures the wall is
+ * proven with, so no plan the proof admits is refused. It is no building rule,
+ * so it names none.
+ */
+export declare function detectPlanOverFreeWall(plan: AiBuildPlan, inventory: AiSiteInventory | null, capabilities: AiPlanCapabilities | null): AiDoctrineViolation[];
+/**
+ * Rule 2 (plan): a layout the plan creates lists the regions it has, and
+ * every one is a region this platform builds (AGL-3024).
+ *
+ * A layout has no properties, so its `fields` are its REGIONS — the promise
+ * the build is later held to. A word the vocabulary does not hold is refused
+ * HERE, on the plan, where the re-ask costs a sentence: a promise nothing can
+ * look for would otherwise reach the build as a commitment no check can
+ * settle, and a build that cannot settle its own plan stops for a person
+ * instead of reporting itself done.
+ */
+export declare function detectPlanUnreadableRegions(plan: AiBuildPlan): AiDoctrineViolation[];
+/**
+ * Every plan rule, against the site inventory the plan was made from and,
+ * where the job read them, what it may create there (AGL-3030). `null`
+ * capabilities restrict nothing: the doctrine applies whole.
+ */
+export declare function validateAiBuildPlan(plan: AiBuildPlan, inventory: AiSiteInventory | null, framing?: AiCopyFraming, capabilities?: AiPlanCapabilities | null): AiDoctrineViolation[];