@aglyn/plugins-ai 1.0.0-beta.143

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

@@ -0,0 +1,372 @@
+/**
+ * @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 { NodesMap } from '@aglyn/aglyn/types/nodes';
+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 { AiStepKind } from '../providers/catalog';
+import { aiStoppedAtCeiling, type AiProvider } from '../providers/contract';
+import { type AiPluginSettings } from '../providers/routing';
+import { type AiEffort, type AiMessage, type AiSystemBlock, type AiThinking, type AiTool, type AiUsage } from './ai-runtime';
+import { type AiCopyFraming, type AiDoctrineTree, type AiDoctrineTreeContext, type AiDoctrineViolation, type AiOutputScore } from './ai-doctrine-validators';
+import { AI_GENERATION_MAX_ATTEMPTS } from './ai-generation-bounds';
+import type { AiNodeTreeContext } from './ai-node-tree';
+import { type AiLoadEstimate, type AiOutputKind, type AiSurface } from './ai-palette';
+/**
+ * What a generation kind produces, and therefore which of the rules below can
+ * bind it (AGL-2937).
+ *
+ * The seventeen rules are written for a kind that composes a DOCUMENT: they
+ * name nodes, instances, layouts, slugs and budgets. A kind that produces
+ * short fields a door checks itself — a page's search listing, an audit's
+ * fixes — can break exactly one of them, and the other sixteen are bytes it
+ * pays for on every attempt without ever being held to them. On a fast-tier
+ * model, whose cached-prefix minimum no SEO prompt reaches, those bytes are
+ * billed at full input rate every single time.
+ *
+ * Sending fewer rules is not only cheaper here, it is more accurate: rule 14
+ * tells a writer to mark a fact it lacks in square brackets, which is right
+ * for page copy a person edits before publishing and wrong for a search title
+ * that is published exactly as written — and the SEO doors' own rules already
+ * say to write only from the text they were given.
+ */
+export type AiDoctrineScope = 
+/** A document the palette composes, or a plan for them: all seventeen rules. */
+'documents'
+/** Values a door reads and checks itself, composing nothing. */
+ | 'fields';
+/**
+ * The procedures in the model's terms, for one scope. Static text only: the
+ * budgets are read from `AI_OUTPUT_BUDGETS` once, at load, so a scope's text
+ * is the same bytes on every request and changes only when a budget does.
+ */
+export declare function aiBuildingDoctrine(scope: AiDoctrineScope): string;
+/** Every rule, as the kinds that compose a document are told them. */
+export declare const AI_BUILDING_DOCTRINE: string;
+/** The doctrine block a kind that composes a document is sent. */
+export declare const AI_DOCTRINE_SYSTEM_BLOCK: AiSystemBlock;
+/** The doctrine block for one scope. */
+export declare function aiDoctrineSystemBlock(scope: AiDoctrineScope): AiSystemBlock;
+/**
+ * The scope a generation kind is told the rules in. A kind absent from this
+ * map composes a document and is told all seventeen — the three SEO kinds are
+ * the only ones today that write values instead, and a new kind that does the
+ * same names itself here rather than paying for rules it cannot break.
+ */
+export declare const AI_DOCTRINE_KIND_SCOPE: Readonly<Record<string, AiDoctrineScope>>;
+/** The scope for a kind; `documents` unless the kind names another. */
+export declare function aiDoctrineScopeFor(kind: string): AiDoctrineScope;
+/**
+ * The inventory as the prompt's VOLATILE block: per site, so it never sits
+ * inside a cached prefix. Held to `AI_SITE_INVENTORY_MAX_CHARS` by cutting
+ * the longest kind a line at a time, each cut kind named, so no one kind can
+ * crowd the others out.
+ *
+ * It lists `AI_SITE_INVENTORY_LISTED_PER_KIND` records of each kind, not the
+ * whole window the reader holds (AGL-2937): the block is billed at full input
+ * rate on every attempt, so a large site would spend most of a plan's prompt
+ * on rows it will not use. A kind with more — cut by the listing cap or by
+ * the read itself — is named as having more, and the sentence points at the
+ * lookup tool the loop offers beside the door's own, so the answer to "is
+ * there already a pricing card?" is a question the model can ask rather than
+ * a gap it fills by creating one.
+ */
+export declare function aiSiteInventoryBlock(inventory: AiSiteInventory | null): string;
+/** What a tree generated against this inventory may reference, for `validateAiNodeTree`. */
+export declare function aiNodeTreeContextFromInventory(inventory: AiSiteInventory | null): AiNodeTreeContext;
+export interface AiDoctrineSystemOptions {
+    /** The door's own static instructions, cached after the doctrine. */
+    instructions?: readonly AiSystemBlock[];
+    /** The palette surface a tree is composed on; its catalog is cached after the instructions. */
+    surface?: AiSurface;
+    /** Which rules the doctrine block states; `documents` when the door names none. */
+    scope?: AiDoctrineScope;
+}
+/**
+ * The palette catalog a generation on this surface is shown: the elements the
+ * surface allows, the props each takes and the named blocks to imitate. The
+ * one reader of it, so a door that composes its own prompt shows the model
+ * the catalog the loop below shows it.
+ */
+export declare function aiDoctrineCatalog(surface: AiSurface): string;
+/**
+ * The system prompt every generator sends, in cache order: the doctrine
+ * (cached), the door's instructions, the surface's palette catalog (cached),
+ * then the site inventory (volatile). With no catalog behind them, the
+ * instructions close the cached prefix themselves. The runtime refuses the
+ * request if a door slips a volatile block inside the cached span.
+ *
+ * `null` is a site whose inventory was not read, and the model is told so;
+ * `undefined` is a kind that builds from no site structure at all — a theme
+ * builds from the theme — and sends no inventory block.
+ */
+export declare function aiDoctrineSystemBlocks(inventory: AiSiteInventory | null | undefined, options?: AiDoctrineSystemOptions): AiSystemBlock[];
+/** What a generation kind is: a document the palette composes, a plan, or a door's own kind. */
+export type AiGenerationKind = AiOutputKind | 'plan';
+/**
+ * `max_tokens` per kind (AGL-2937): the ceiling of one answer, sized to the
+ * kind's budget with room for the model's reasoning. A kind a door brings
+ * with its own check takes `AI_CUSTOM_GENERATION_MAX_TOKENS` unless the door
+ * names its own.
+ */
+export declare const AI_GENERATION_MAX_TOKENS: Record<AiGenerationKind, number>;
+export declare const AI_CUSTOM_GENERATION_MAX_TOKENS = 8000;
+/** One answer, and one re-ask with the violations named. */
+export { AI_GENERATION_MAX_ATTEMPTS };
+/** How much of the offending parts a re-ask quotes. */
+export declare const AI_REASK_OFFENDING_MAX_CHARS = 6000;
+export declare function isAiOutputKind(kind: string): kind is AiOutputKind;
+/** What one check made of one answer. */
+export interface AiGenerationCheckResult<T> {
+    /** The value to keep; `null` when the answer could not be read as one. */
+    value: T | null;
+    violations: AiDoctrineViolation[];
+    /** The parts of the answer at fault, keyed as the model wrote them, for the re-ask. */
+    offending?: Record<string, unknown>;
+}
+export type AiGenerationCheck<T> = (answer: Record<string, unknown>) => AiGenerationCheckResult<T>;
+/** A tree that passed the palette validator and every doctrine rule. */
+export interface AiValidatedTree {
+    rootId: string;
+    nodes: NodesMap;
+    /** What the palette validator dropped or normalized on the way in. */
+    repairs: string[];
+    /** Each minted id → the id the model wrote for that node. */
+    sourceIds: Record<string, string>;
+    score: AiOutputScore;
+    /** The weight the proposal shows; `null` for an email. */
+    load: AiLoadEstimate | null;
+}
+/**
+ * The strict tool a tree arrives through. The node map rides as JSON text:
+ * a map keyed by the model's own node ids has no fixed properties, and a
+ * strict schema must close every object it declares.
+ */
+export declare function aiDoctrineTreeTool(kind: AiOutputKind): AiTool;
+/** The tree a tool answer carries: `tree` as an object or JSON text, else the answer itself. */
+export declare function aiAnswerTree(answer: Record<string, unknown>): unknown;
+/**
+ * The doctrine's check for a tree kind: the palette validator, every tree
+ * rule and the budget, with each offending node reported and quoted by the
+ * id the MODEL wrote — the minted ids are ones it never saw.
+ */
+export declare function aiDoctrineTreeCheck(kind: AiOutputKind, context?: AiDoctrineTreeContext, otherPages?: readonly AiDoctrineTree[]): AiGenerationCheck<AiValidatedTree>;
+/**
+ * The doctrine's check for a plan: its shape, then every plan rule against
+ * the inventory and, where the job read them, against what it may create on
+ * the site (AGL-3030).
+ */
+export declare function aiDoctrinePlanCheck(inventory: AiSiteInventory | null, framing?: AiCopyFraming, capabilities?: AiPlanCapabilities | null): AiGenerationCheck<AiBuildPlan>;
+/** The finding an answer that ran past its output ceiling is refused for (AGL-3042). */
+export declare const AI_ANSWER_CUT_OFF_CODE = "answer-cut-off";
+/**
+ * Whether a model call stopped at its output ceiling (AGL-3042). The
+ * contract owns the predicate, because an adapter reads it to decide whether
+ * to keep the call's raw output; the doctrine re-exports it, which is where
+ * every door already reads it from.
+ */
+export { aiStoppedAtCeiling };
+/**
+ * How a door names what it generates, and what makes it smaller, for an
+ * answer cut off at its ceiling (AGL-3042).
+ */
+export interface AiGenerationCutOff {
+    /** What a person calls the output: `section` reads "This section was too large to build in one pass." */
+    noun: string;
+    /**
+     * What the re-ask tells the model makes an answer of this kind smaller, in
+     * its own sentence: a section's element budget, shorter copy, a repeated
+     * item placed as an instance.
+     */
+    smaller: string;
+}
+/**
+ * The re-ask: the rules broken, where, and the offending parts as the model
+ * wrote them. An answer cut off at its ceiling is told that first, with what
+ * makes it smaller (AGL-3042): it broke no rule it can mend by reading one,
+ * and asking for the same answer again is asking to be cut off again.
+ */
+export declare function aiReaskMessage(kind: string, toolName: string, violations: readonly AiDoctrineViolation[], offending?: Record<string, unknown>): string;
+/**
+ * What a person reads when the second answer still broke a rule. An answer
+ * cut off at its ceiling broke none (AGL-3042), so its own sentence is what
+ * they read: it was too large, and what helps.
+ */
+export declare function aiDoctrineNeedsInputMessage(violations: readonly AiDoctrineViolation[]): string;
+interface AiGenerationInputBase {
+    /**
+     * The routing table's step kind: it decides the model (never a model
+     * literal) unless `model` names one already resolved. One of the two is
+     * required.
+     */
+    step?: AiStepKind;
+    /** The org's resolved `pluginSettings/ai`, for its provider and model choices. */
+    settings?: AiPluginSettings;
+    /** A route the door already resolved; the routing table's answer for `step` otherwise. */
+    model?: string;
+    /** The door's own static instructions. */
+    instructions: readonly AiSystemBlock[];
+    /** The site the output is built for; `null` when none was read. */
+    inventory: AiSiteInventory | null;
+    /** The brief and whatever the door sends in the user turn. */
+    messages: readonly AiMessage[];
+    /** The strict tool the answer arrives through. */
+    tool: AiTool;
+    /**
+     * The ceiling of one answer; `AI_GENERATION_MAX_TOKENS` for the kind when
+     * absent. The whole generation — its answers and every lookup round before
+     * them — spends at most `AI_GENERATION_MAX_ATTEMPTS` of it (AGL-3036).
+     */
+    maxTokens?: number;
+    /**
+     * What the output is called, and what makes it smaller, when an answer is
+     * cut off at `maxTokens` (AGL-3042). Absent, a plan or a palette kind is
+     * called by its kind, any other output an answer, and the model is asked
+     * for a smaller one of its kind.
+     */
+    cutOff?: AiGenerationCutOff;
+    thinking?: AiThinking;
+    effort?: AiEffort;
+    signal?: AbortSignal;
+    /** A provider chosen ahead of every setting; specs use it. */
+    provider?: AiProvider;
+}
+export interface AiTreeGenerationInput extends AiGenerationInputBase {
+    /** What the tree rules read beyond the inventory: asset sizes, the brand, embeds, framing. */
+    context?: AiDoctrineTreeContext;
+    /** Trees generated beside this one, for rule 1 across pages. */
+    otherPages?: readonly AiDoctrineTree[];
+    /** Checks the door adds to the doctrine's own, run on a tree the doctrine admitted. */
+    extend?: (tree: AiValidatedTree, answer: Record<string, unknown>) => AiDoctrineViolation[];
+}
+export interface AiPlanGenerationInput extends AiGenerationInputBase {
+    framing?: AiCopyFraming;
+    /**
+     * What the job may create on its site (AGL-3030). The plan rules refuse a
+     * creation outside it, and build inline where the workspace keeps no
+     * reusable components; absent, the doctrine applies whole.
+     */
+    capabilities?: AiPlanCapabilities | null;
+    /** Checks the door adds to the doctrine's own, run on a plan that parsed. */
+    extend?: (plan: AiBuildPlan, answer: Record<string, unknown>) => AiDoctrineViolation[];
+}
+export interface AiCustomGenerationInput<T> extends Omit<AiGenerationInputBase, 'inventory'> {
+    /**
+     * The site the output is built for, `null` when none was read. A kind that
+     * builds from no site structure — a theme builds from the theme — leaves it
+     * out, and no inventory block is sent.
+     */
+    inventory?: AiSiteInventory | null;
+    /**
+     * How a kind the doctrine has no reader for is read and checked — a theme
+     * change, an edit. Rule 13 is held on every answer whatever it returns.
+     */
+    check: AiGenerationCheck<T>;
+}
+/** What a generation spent, whatever its outcome. */
+export interface AiGenerationSpend {
+    /**
+     * Model calls made, all of which the meter bills: one per answer — 2 when
+     * the first was re-asked — plus one per site-inventory lookup answered
+     * along the way (AGL-2937).
+     */
+    attempts: number;
+    /** Tokens across every attempt; the meter bills all of them. */
+    usage: AiUsage;
+    estCostUsd: number;
+    model: string;
+    stopReason: string | null;
+    /** The thinking effort the requests asked for; `null` when they named none. */
+    effort: AiEffort | null;
+}
+export type AiValidatedGeneration<T> = (AiGenerationSpend & {
+    status: 'ok';
+    value: T;
+})
+/** The re-ask still broke a rule: a person decides. `message` is customer-safe. */
+ | (AiGenerationSpend & {
+    status: 'needs_input';
+    violations: AiDoctrineViolation[];
+    message: string;
+    /**
+     * The answer the violations were found in, as it came through the tool
+     * (AGL-3078): what a job's review outlines the parts they name from.
+     * Held in memory only, and `null` when no answer arrived.
+     */
+    answer?: Record<string, unknown> | null;
+    /**
+     * What the provider wrote for the attempt its ceiling cut off
+     * (AGL-3143), when it sent it: the bytes behind `answer`, which is only
+     * as much of them as still parsed. Held in memory only, like `answer`,
+     * and `null` when nothing was cut off. It is the trace's, never a
+     * customer's — a caller that keeps it keeps it out of what it shows.
+     */
+    rawOutput?: string | null;
+})
+/** The model declined; tokens were spent. */
+ | (AiGenerationSpend & {
+    status: 'refused';
+});
+/**
+ * What a tree built for this site is checked against: the brand an email is
+ * held to, the ids the inventory lists, and whatever the door adds — asset
+ * sizes, embeds, framing.
+ */
+export declare function aiDoctrineTreeContext(inventory: AiSiteInventory | null, extra?: AiDoctrineTreeContext): AiDoctrineTreeContext;
+/**
+ * Generate one output under the doctrine: ask, check, re-ask once with the
+ * violations named, and give up with `needs_input` rather than spend again.
+ *
+ * `kind` decides the check: `'plan'` and the six palette kinds are read and
+ * held by the doctrine itself; any other kind brings its own `check`, and the
+ * doctrine still holds rule 13 on it. Throws only what the runtime throws — a
+ * provider failure, an abort, a prompt the cache guard refuses — so a job
+ * step's retry and failure paths stay the machine's.
+ */
+export declare function runValidatedGeneration(kind: 'plan', input: AiPlanGenerationInput): Promise<AiValidatedGeneration<AiBuildPlan>>;
+export declare function runValidatedGeneration(kind: AiOutputKind, input: AiTreeGenerationInput): Promise<AiValidatedGeneration<AiValidatedTree>>;
+export declare function runValidatedGeneration<T>(kind: string, input: AiCustomGenerationInput<T>): Promise<AiValidatedGeneration<T>>;
+/** What a streamed answer came to: a value with what its check left out, or the reasons there is none. */
+export type AiStreamedGeneration<T> = {
+    status: 'ok';
+    value: T;
+    violations: AiDoctrineViolation[];
+}
+/** No value, or a numbered rule broken. `message` is customer-safe. */
+ | {
+    status: 'needs_input';
+    violations: AiDoctrineViolation[];
+    message: string;
+};
+/**
+ * An answer a door has already received, held to the doctrine without a
+ * request. A door that streams its reply to the reader as it arrives — the
+ * chat door's edit rung — can read the answer only once it is on screen, with
+ * no turn left to re-ask in, so the loop above cannot carry it.
+ *
+ * The check is the loop's for a kind the doctrine has no reader for: the
+ * door's own, with rule 13 held on the answer. So are the verdicts, less the
+ * re-ask. No value, or a numbered rule broken, is `needs_input` with the
+ * reasons. A value is `ok` with the door's own findings beside it — what its
+ * check already left out of the value, such as the changes an edit could not
+ * make. A plan or a palette kind is refused here: the loop reads those, and a
+ * broken rule in one is asked for again, never kept.
+ */
+export declare function validateStreamedGeneration<T>(kind: string, input: {
+    answer: Record<string, unknown>;
+    check: AiGenerationCheck<T>;
+}): AiStreamedGeneration<T>;