@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/model/ai-experiment-proposal.js

@@ -0,0 +1,146 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { AI_EXPERIMENT_MAX_VARIANTS, AI_EXPERIMENT_TARGETS, aiExperimentNextStep, aiExperimentVerdictNamesWinner } from "./ai-experiment.js";
+/**
+ * An `experiment` job's answer, read back from the output a console surface
+ * received, and what a surface is allowed to show of it (AGL-2914).
+ *
+ * The step decided the verdict from the counts and cut the model's words back
+ * to it. That work is undone the moment a card draws the answer with a
+ * confident heading, a highlighted arm or a "recommended" badge, because a
+ * reader takes the layout for the claim and never reads the sentence that
+ * hedges it. So the reading of the verdict happens ONCE more, here, in code a
+ * surface cannot skip: {@link aiExperimentVerdictDisplay} says what tone a
+ * verdict is drawn in and whether ANY arm may be marked, and an undecided
+ * result answers `false` however the proposal was filled in.
+ *
+ * ## The proposal is not trusted to describe itself
+ *
+ * An output's `proposal` is a plain record by the time it reaches a browser:
+ * it came back over HTTP, out of a document a job wrote. A `winnerId` in it
+ * beside a verdict of `inconclusive` is therefore possible — not because the
+ * step would write one, but because nothing between here and there is typed.
+ * {@link readAiExperimentExplanation} drops it, rather than trusting the
+ * field that would have been the model's if the step had not already taken it
+ * away.
+ */ const isRecord = (value)=>typeof value === 'object' && value !== null && !Array.isArray(value);
+const text = (value)=>typeof value === 'string' ? value.trim() : '';
+const count = (value)=>typeof value === 'number' && Number.isFinite(value) ? Math.max(0, value) : 0;
+const percent = (value)=>typeof value === 'number' && Number.isFinite(value) ? value : null;
+const VERDICTS = [
+    'unreadable',
+    'too-early',
+    'inconclusive',
+    'winner',
+    'control'
+];
+const DISPLAY = {
+    winner: {
+        namesAnArm: true,
+        tone: 'success',
+        status: 'One variant is ahead',
+        caveat: ''
+    },
+    control: {
+        namesAnArm: true,
+        tone: 'success',
+        status: 'The first variant is ahead',
+        caveat: ''
+    },
+    'too-early': {
+        namesAnArm: false,
+        tone: 'default',
+        status: 'No result yet',
+        caveat: 'This test has not answered yet. No variant is ahead of another.'
+    },
+    inconclusive: {
+        namesAnArm: false,
+        tone: 'default',
+        status: 'No winner',
+        caveat: 'This test did not settle anything. No variant is ahead of another.'
+    },
+    unreadable: {
+        namesAnArm: false,
+        tone: 'default',
+        status: 'Nothing to read',
+        caveat: 'There is nothing here to compare, so nothing is ahead.'
+    }
+};
+/** How a verdict is drawn; an unknown verdict is drawn as the most careful one. */ export function aiExperimentVerdictDisplay(verdict) {
+    var _DISPLAY_verdict;
+    return (_DISPLAY_verdict = DISPLAY[verdict]) != null ? _DISPLAY_verdict : DISPLAY['unreadable'];
+}
+/**
+ * Whether a surface may mark this arm. The verdict decides first, so an arm
+ * cannot be marked on a result that named none, whatever `winnerId` holds.
+ */ export function aiExperimentArmIsNamed(explanation, armId) {
+    return aiExperimentVerdictNamesWinner(explanation.verdict) && explanation.winnerId !== null && explanation.winnerId === armId;
+}
+/** An explanation output's proposal, or `null` when it is not one. */ export function readAiExperimentExplanation(value) {
+    var _percent;
+    if (!isRecord(value) || value['task'] !== 'explain') return null;
+    const verdict = VERDICTS.includes(value['verdict']) ? value['verdict'] : null;
+    const headline = text(value['headline']);
+    if (!verdict || !headline) return null;
+    const arms = (Array.isArray(value['arms']) ? value['arms'] : []).filter(isRecord).map((arm)=>({
+            id: text(arm['id']),
+            exposures: count(arm['exposures']),
+            conversions: count(arm['conversions']),
+            rate: percent(arm['rate']),
+            lift: percent(arm['lift']),
+            confidence: percent(arm['confidence'])
+        })).filter((arm)=>arm.id).slice(0, AI_EXPERIMENT_MAX_VARIANTS);
+    const named = text(value['winnerId']);
+    // The verdict decides whether there is an arm to name, and the arm must be
+    // one the figures carry. A name that passes neither test is dropped rather
+    // than shown beside a result that does not support it.
+    const winnerId = aiExperimentVerdictNamesWinner(verdict) && named && arms.some((arm)=>arm.id === named) ? named : null;
+    const answered = text(value['next']);
+    return {
+        verdict,
+        test: text(value['test']),
+        headline,
+        points: (Array.isArray(value['points']) ? value['points'] : []).map(text).filter(Boolean),
+        winnerId,
+        // Undecided, the next step is the verdict's own sentence — the same one
+        // the step substituted — so a surface reading an older document still
+        // shows code's answer rather than whatever was stored beside it.
+        next: aiExperimentVerdictNamesWinner(verdict) ? answered : aiExperimentNextStep(verdict),
+        threshold: (_percent = percent(value['threshold'])) != null ? _percent : 0,
+        arms
+    };
+}
+/** A variants output's proposal, or `null` when it is not one. */ export function readAiExperimentVariants(value) {
+    if (!isRecord(value) || value['task'] !== 'variants') return null;
+    const target = AI_EXPERIMENT_TARGETS.includes(String(value['target'])) ? value['target'] : null;
+    if (!target) return null;
+    const variants = (Array.isArray(value['variants']) ? value['variants'] : []).filter(isRecord).map((variant)=>({
+            name: text(variant['name']),
+            headline: text(variant['headline']),
+            body: text(variant['body']),
+            subject: text(variant['subject']),
+            preheader: text(variant['preheader']),
+            rationale: text(variant['rationale'])
+        })).filter((variant)=>variant.headline || variant.body || variant.subject).slice(0, AI_EXPERIMENT_MAX_VARIANTS);
+    if (!variants.length) return null;
+    return {
+        target,
+        goal: text(value['goal']),
+        variants
+    };
+}
+
+//# sourceMappingURL=ai-experiment-proposal.js.map

package/src/lib/model/ai-experiment-proposal.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/model/ai-experiment-proposal.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  AI_EXPERIMENT_MAX_VARIANTS,\n  AI_EXPERIMENT_TARGETS,\n  aiExperimentNextStep,\n  aiExperimentVerdictNamesWinner,\n  type AiExperimentArm,\n  type AiExperimentTarget,\n  type AiExperimentVariantProposal,\n  type AiExperimentVerdict,\n} from './ai-experiment'\n\n/**\n * An `experiment` job's answer, read back from the output a console surface\n * received, and what a surface is allowed to show of it (AGL-2914).\n *\n * The step decided the verdict from the counts and cut the model's words back\n * to it. That work is undone the moment a card draws the answer with a\n * confident heading, a highlighted arm or a \"recommended\" badge, because a\n * reader takes the layout for the claim and never reads the sentence that\n * hedges it. So the reading of the verdict happens ONCE more, here, in code a\n * surface cannot skip: {@link aiExperimentVerdictDisplay} says what tone a\n * verdict is drawn in and whether ANY arm may be marked, and an undecided\n * result answers `false` however the proposal was filled in.\n *\n * ## The proposal is not trusted to describe itself\n *\n * An output's `proposal` is a plain record by the time it reaches a browser:\n * it came back over HTTP, out of a document a job wrote. A `winnerId` in it\n * beside a verdict of `inconclusive` is therefore possible — not because the\n * step would write one, but because nothing between here and there is typed.\n * {@link readAiExperimentExplanation} drops it, rather than trusting the\n * field that would have been the model's if the step had not already taken it\n * away.\n */\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value)\n\nconst text = (value: unknown): string =>\n  typeof value === 'string' ? value.trim() : ''\n\nconst count = (value: unknown): number =>\n  typeof value === 'number' && Number.isFinite(value) ? Math.max(0, value) : 0\n\nconst percent = (value: unknown): number | null =>\n  typeof value === 'number' && Number.isFinite(value) ? value : null\n\nconst VERDICTS: readonly AiExperimentVerdict[] = [\n  'unreadable',\n  'too-early',\n  'inconclusive',\n  'winner',\n  'control',\n]\n\n/** An explanation as a console surface reads it back. */\nexport interface AiExperimentExplanationProposal {\n  verdict: AiExperimentVerdict\n  test: string\n  headline: string\n  points: string[]\n  /** The arm the FIGURES named, and only ever on a verdict that names one. */\n  winnerId: string | null\n  next: string\n  /** The confidence one comparison had to clear, as a percentage. */\n  threshold: number\n  arms: AiExperimentArm[]\n}\n\n/** A variants answer as a console surface reads it back. */\nexport interface AiExperimentVariantsProposalView {\n  target: AiExperimentTarget\n  goal: string\n  variants: AiExperimentVariantProposal[]\n}\n\n/**\n * How a verdict is drawn.\n *\n * `namesAnArm` is the one a surface must ask before it marks a row, a chip or\n * a heading: on `too-early`, `inconclusive` and `unreadable` there is no arm\n * to mark, and marking the one with the best rate anyway is the claim the\n * step refused to let the model make.\n *\n * `tone` is a MUI severity/color word rather than a color: `success` only\n * where the figures decided something, and the neutral `default` everywhere\n * else — an undecided result drawn in a color that reads as good or as bad\n * says something the figures did not.\n */\nexport interface AiExperimentVerdictDisplay {\n  namesAnArm: boolean\n  tone: 'success' | 'default'\n  /** The verdict in a reader's words, short enough for a chip. */\n  status: string\n  /** What the result does not settle, or empty where it settles something. */\n  caveat: string\n}\n\nconst DISPLAY: Record<AiExperimentVerdict, AiExperimentVerdictDisplay> = {\n  winner: {\n    namesAnArm: true,\n    tone: 'success',\n    status: 'One variant is ahead',\n    caveat: '',\n  },\n  control: {\n    namesAnArm: true,\n    tone: 'success',\n    status: 'The first variant is ahead',\n    caveat: '',\n  },\n  'too-early': {\n    namesAnArm: false,\n    tone: 'default',\n    status: 'No result yet',\n    caveat: 'This test has not answered yet. No variant is ahead of another.',\n  },\n  inconclusive: {\n    namesAnArm: false,\n    tone: 'default',\n    status: 'No winner',\n    caveat:\n      'This test did not settle anything. No variant is ahead of another.',\n  },\n  unreadable: {\n    namesAnArm: false,\n    tone: 'default',\n    status: 'Nothing to read',\n    caveat: 'There is nothing here to compare, so nothing is ahead.',\n  },\n}\n\n/** How a verdict is drawn; an unknown verdict is drawn as the most careful one. */\nexport function aiExperimentVerdictDisplay(\n  verdict: AiExperimentVerdict | string,\n): AiExperimentVerdictDisplay {\n  return DISPLAY[verdict as AiExperimentVerdict] ?? DISPLAY['unreadable']\n}\n\n/**\n * Whether a surface may mark this arm. The verdict decides first, so an arm\n * cannot be marked on a result that named none, whatever `winnerId` holds.\n */\nexport function aiExperimentArmIsNamed(\n  explanation: Pick<AiExperimentExplanationProposal, 'verdict' | 'winnerId'>,\n  armId: string,\n): boolean {\n  return (\n    aiExperimentVerdictNamesWinner(explanation.verdict) &&\n    explanation.winnerId !== null &&\n    explanation.winnerId === armId\n  )\n}\n\n/** An explanation output's proposal, or `null` when it is not one. */\nexport function readAiExperimentExplanation(\n  value: unknown,\n): AiExperimentExplanationProposal | null {\n  if (!isRecord(value) || value['task'] !== 'explain') return null\n  const verdict = VERDICTS.includes(value['verdict'] as AiExperimentVerdict)\n    ? (value['verdict'] as AiExperimentVerdict)\n    : null\n  const headline = text(value['headline'])\n  if (!verdict || !headline) return null\n  const arms = (Array.isArray(value['arms']) ? value['arms'] : [])\n    .filter(isRecord)\n    .map((arm): AiExperimentArm => ({\n      id: text(arm['id']),\n      exposures: count(arm['exposures']),\n      conversions: count(arm['conversions']),\n      rate: percent(arm['rate']),\n      lift: percent(arm['lift']),\n      confidence: percent(arm['confidence']),\n    }))\n    .filter((arm) => arm.id)\n    .slice(0, AI_EXPERIMENT_MAX_VARIANTS)\n  const named = text(value['winnerId'])\n  // The verdict decides whether there is an arm to name, and the arm must be\n  // one the figures carry. A name that passes neither test is dropped rather\n  // than shown beside a result that does not support it.\n  const winnerId =\n    aiExperimentVerdictNamesWinner(verdict) &&\n    named &&\n    arms.some((arm) => arm.id === named)\n      ? named\n      : null\n  const answered = text(value['next'])\n  return {\n    verdict,\n    test: text(value['test']),\n    headline,\n    points: (Array.isArray(value['points']) ? value['points'] : [])\n      .map(text)\n      .filter(Boolean),\n    winnerId,\n    // Undecided, the next step is the verdict's own sentence — the same one\n    // the step substituted — so a surface reading an older document still\n    // shows code's answer rather than whatever was stored beside it.\n    next: aiExperimentVerdictNamesWinner(verdict)\n      ? answered\n      : aiExperimentNextStep(verdict),\n    threshold: percent(value['threshold']) ?? 0,\n    arms,\n  }\n}\n\n/** A variants output's proposal, or `null` when it is not one. */\nexport function readAiExperimentVariants(\n  value: unknown,\n): AiExperimentVariantsProposalView | null {\n  if (!isRecord(value) || value['task'] !== 'variants') return null\n  const target = (AI_EXPERIMENT_TARGETS as readonly string[]).includes(\n    String(value['target']),\n  )\n    ? (value['target'] as AiExperimentTarget)\n    : null\n  if (!target) return null\n  const variants = (Array.isArray(value['variants']) ? value['variants'] : [])\n    .filter(isRecord)\n    .map((variant): AiExperimentVariantProposal => ({\n      name: text(variant['name']),\n      headline: text(variant['headline']),\n      body: text(variant['body']),\n      subject: text(variant['subject']),\n      preheader: text(variant['preheader']),\n      rationale: text(variant['rationale']),\n    }))\n    .filter((variant) => variant.headline || variant.body || variant.subject)\n    .slice(0, AI_EXPERIMENT_MAX_VARIANTS)\n  if (!variants.length) return null\n  return { target, goal: text(value['goal']), variants }\n}\n"],"names":["AI_EXPERIMENT_MAX_VARIANTS","AI_EXPERIMENT_TARGETS","aiExperimentNextStep","aiExperimentVerdictNamesWinner","isRecord","value","Array","isArray","text","trim","count","Number","isFinite","Math","max","percent","VERDICTS","DISPLAY","winner","namesAnArm","tone","status","caveat","control","inconclusive","unreadable","aiExperimentVerdictDisplay","verdict","aiExperimentArmIsNamed","explanation","armId","winnerId","readAiExperimentExplanation","includes","headline","arms","filter","map","arm","id","exposures","conversions","rate","lift","confidence","slice","named","some","answered","test","points","Boolean","next","threshold","readAiExperimentVariants","target","String","variants","variant","name","body","subject","preheader","rationale","length","goal"],"mappings":"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"}

package/src/lib/model/ai-experiment.d.ts

@@ -0,0 +1,309 @@
+/**
+ * @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 { PluginFigureTable } from '@aglyn/aglyn/plugin-manager/plugin-figures';
+/**
+ * A/B tests by AI (AGL-2914): what an `experiment` job proposes, and what it
+ * is allowed to say about a result.
+ *
+ * ## The test is not ours
+ *
+ * A/B testing is the marketing plugin's: it models the experiment document,
+ * buckets visitors, counts exposures and conversions, compares a challenger
+ * with the control and decides an auto-winner. None of that is restated here,
+ * and none of it is imported — a plugin never imports another plugin. This
+ * module is the AI layer over it, and it reaches the test through the two
+ * generic seams core already publishes: the figure reader marketing registers
+ * for its results, and the job inputs a console surface hands the door.
+ *
+ * ## Variants are proposed, never written
+ *
+ * A variant of a screen or a section is a screen VERSION, and a variant of an
+ * email is that email's own copy: both belong to editors a person already
+ * uses, and the experiment document belongs to marketing. So a variants
+ * answer is a proposal, like a theme's or a listing's — words a person puts
+ * into the A/B testing card, or does not. Nothing here writes an experiment,
+ * starts one, or moves traffic.
+ *
+ * ## The verdict is code's, and the words are the model's
+ *
+ * `readAiExperimentResult` decides what a result supports BEFORE a model is
+ * asked anything, from the arms' own counts and the confidence marketing
+ * published beside them. The model is then asked to explain that verdict, and
+ * `checkAiExperimentExplanation` holds it to it: an explanation may name a
+ * winner only where the reading found one, and a winner it names anyway is
+ * dropped rather than shown. A confident explanation of noise is worse than
+ * no explanation, so the one thing the model is never trusted with is whether
+ * there is something to explain.
+ */
+/** What an `experiment` job was asked for. */
+export type AiExperimentTask = 'variants' | 'explain';
+export declare const AI_EXPERIMENT_TASKS: readonly AiExperimentTask[];
+/** The task a job's inputs name, or `null` when they name none this step runs. */
+export declare function aiExperimentTask(inputs: Readonly<Record<string, unknown>> | null | undefined): AiExperimentTask | null;
+/**
+ * What the experiment varies, in the words the A/B testing card uses. The job
+ * carries it as an input because the card that opens the job knows it; it is
+ * never read out of marketing's own document.
+ */
+export type AiExperimentTarget = 'screen' | 'section' | 'email';
+export declare const AI_EXPERIMENT_TARGETS: readonly AiExperimentTarget[];
+/** The target a job's inputs name, or `null` when they name none. */
+export declare function aiExperimentTarget(inputs: Readonly<Record<string, unknown>> | null | undefined): AiExperimentTarget | null;
+/**
+ * How many variants a proposal may hold, the cap the A/B testing card stores
+ * and the page runner buckets against. Proposing a fifth would be proposing
+ * something nothing can save.
+ */
+export declare const AI_EXPERIMENT_MAX_VARIANTS = 4;
+/** The fewest a test can be: a control and one challenger. */
+export declare const AI_EXPERIMENT_MIN_VARIANTS = 2;
+/** How long a variant's name may run, as the card's own field holds one. */
+export declare const AI_EXPERIMENT_NAME_MAX_CHARS = 60;
+/** How long one line of a variant's copy may run. */
+export declare const AI_EXPERIMENT_LINE_MAX_CHARS = 200;
+/** How long a variant's body may run. */
+export declare const AI_EXPERIMENT_BODY_MAX_CHARS = 1200;
+/** How long the sentence saying what a variant changes may run. */
+export declare const AI_EXPERIMENT_RATIONALE_MAX_CHARS = 200;
+/** How much of what is under test is sent. Past this it is a document, not a subject. */
+export declare const AI_EXPERIMENT_SUBJECT_MAX_CHARS = 4000;
+/**
+ * One variant a proposal holds. `headline` and `body` are a screen's or a
+ * section's copy; `subject` and `preheader` are an email's. A variant carries
+ * the fields its target has and leaves the rest empty, so what a person pastes
+ * into the card is what that card has a place for.
+ */
+export interface AiExperimentVariantProposal {
+    name: string;
+    headline: string;
+    body: string;
+    subject: string;
+    preheader: string;
+    /** One sentence: what this variant changes and what it is testing. */
+    rationale: string;
+}
+/** A variants answer as the step keeps it. */
+export interface AiExperimentVariantsProposal {
+    /** What the variants are trying to move, in the person's own terms. */
+    goal: string;
+    variants: AiExperimentVariantProposal[];
+}
+/**
+ * The reader marketing registers for its A/B test results, and the columns it
+ * publishes. Named here rather than imported because the owner is another
+ * plugin: a table that does not carry these columns is one this step cannot
+ * read, and it says so instead of guessing.
+ */
+export declare const AI_EXPERIMENT_FIGURE_READER = "marketing.experiments";
+export declare const AI_EXPERIMENT_FIGURE_COLUMNS: {
+    readonly test: "test";
+    readonly variant: "variant";
+    readonly exposures: "shown";
+    readonly conversions: "conversions";
+    readonly rate: "rate";
+    readonly lift: "lift";
+    readonly confidence: "confidence";
+};
+/**
+ * One arm of a test, as the figures report it. `lift` and `confidence` are the
+ * owner's own comparison against the control, as percentages, and are `null`
+ * on the control row and wherever the owner could not compare.
+ */
+export interface AiExperimentArm {
+    id: string;
+    /** The exposures the reader counted: visitors shown this arm. */
+    exposures: number;
+    conversions: number;
+    /** Conversions over exposures, as a percentage; `null` with no exposures. */
+    rate: number | null;
+    /** Relative change against the control, as a percentage; `null` on the control. */
+    lift: number | null;
+    /** The owner's confidence that this arm beats the control, as a percentage. */
+    confidence: number | null;
+}
+/**
+ * The exposures each arm needs before a comparison is read at all. Below this
+ * a test is early rather than inconclusive, which is a different thing to tell
+ * someone: one says wait, the other says stop.
+ */
+export declare const AI_EXPERIMENT_MIN_EXPOSURES = 200;
+/**
+ * The successes and failures each arm needs, at the pooled rate, for the
+ * normal approximation behind a two-proportion test to be worth reading. The
+ * textbook condition, and the reason a test with plenty of traffic and almost
+ * no conversions is still too early to call.
+ */
+export declare const AI_EXPERIMENT_MIN_EXPECTED = 5;
+/**
+ * The confidence a single comparison is called at: the same 95% the A/B
+ * testing card's auto-winner offers, so the explanation and the card agree
+ * about what "confident" means when there is one challenger.
+ */
+export declare const AI_EXPERIMENT_CONFIDENCE = 0.95;
+/**
+ * The confidence ONE comparison must clear when a test has `challengers` of
+ * them (Šidák): testing three challengers at 95% each would call a winner by
+ * chance about one time in seven, so the bar rises with the number of chances
+ * taken. With one challenger this is exactly `AI_EXPERIMENT_CONFIDENCE`.
+ */
+export declare function aiExperimentConfidenceThreshold(challengers: number): number;
+/**
+ * What a result supports:
+ *
+ * - `unreadable` — the figures do not describe a test with a control and a
+ *   challenger, so there is nothing to read;
+ * - `too-early` — an arm is under the exposure floor, or so little has
+ *   converted that the comparison behind the confidence is not worth reading;
+ * - `inconclusive` — enough has happened, and no arm is far enough from the
+ *   control for the difference to be more than chance;
+ * - `winner` — a challenger is ahead by more than chance explains;
+ * - `control` — every challenger is behind by more than chance explains.
+ */
+export type AiExperimentVerdict = 'unreadable' | 'too-early' | 'inconclusive' | 'winner' | 'control';
+/** The verdicts that name an arm, and so let an explanation name one. */
+export declare const AI_EXPERIMENT_DECIDED_VERDICTS: readonly AiExperimentVerdict[];
+/** Whether a verdict lets an explanation name a winner. */
+export declare function aiExperimentVerdictNamesWinner(verdict: AiExperimentVerdict): boolean;
+export interface AiExperimentReading {
+    verdict: AiExperimentVerdict;
+    /** The test's name as the figures label it. */
+    test: string;
+    /** The control first, then its challengers in the order the figures gave them. */
+    arms: AiExperimentArm[];
+    /** The arm the verdict names, on `winner` and `control`; `null` otherwise. */
+    winnerId: string | null;
+    /** The confidence one comparison had to clear, as a percentage. */
+    threshold: number;
+    /**
+     * Why the verdict is not a winner, in the words the explanation is asked to
+     * use; empty where it is one. Never a number — the figures carry those.
+     */
+    reasons: string[];
+}
+/** Whether a table is the A/B test results, by the columns it publishes. */
+export declare function isAiExperimentTable(table: Pick<PluginFigureTable, 'columns'> | null | undefined): boolean;
+/** The tests a results table holds, by the name it labels each with. */
+export declare function aiExperimentTestNames(table: Pick<PluginFigureTable, 'columns' | 'rows'> | null | undefined): string[];
+/**
+ * One test's arms, in the order the table gave them — the control first, as
+ * the reader's own note says it publishes them. An empty list where the table
+ * is not the results, or holds no such test.
+ */
+export declare function readAiExperimentArms(table: Pick<PluginFigureTable, 'columns' | 'rows'> | null | undefined, test: string): AiExperimentArm[];
+/** What an arm is told to wait for, in words with no figure in them. */
+export declare const AI_EXPERIMENT_REASON_EXPOSURES = "at least one variant has not been shown to enough visitors yet";
+export declare const AI_EXPERIMENT_REASON_CONVERSIONS = "too little has converted yet for the comparison to mean anything";
+export declare const AI_EXPERIMENT_REASON_SPREAD = "no variant is far enough from the first one for the difference to be more than chance";
+export declare const AI_EXPERIMENT_REASON_UNREADABLE = "these figures do not describe a test with a first variant and something to compare against it";
+/**
+ * What a test's figures support (AGL-2914), decided before a model is asked
+ * anything.
+ *
+ * The first arm is the control, as the results reader publishes it. A verdict
+ * is reached in this order, and the first answer wins:
+ *
+ * 1. fewer than two arms — `unreadable`;
+ * 2. an arm under `AI_EXPERIMENT_MIN_EXPOSURES`, or one whose expected
+ *    successes or failures at the pooled rate are under
+ *    `AI_EXPERIMENT_MIN_EXPECTED` — `too-early`. The second is what stops a
+ *    test with a hundred thousand visitors and four conversions reading as a
+ *    decided one;
+ * 3. a challenger whose confidence clears the multiplicity-corrected
+ *    threshold — `winner`, the most confident of them;
+ * 4. every challenger below `1 - threshold`, which is the same statement made
+ *    about the control — `control`;
+ * 5. anything else — `inconclusive`.
+ *
+ * A challenger the owner could not compare (`confidence` is `null`) can never
+ * win, and leaves the control undecided too: not knowing is not evidence.
+ */
+export declare function readAiExperimentResult(test: string, arms: readonly AiExperimentArm[]): AiExperimentReading;
+/** How long the sentence stating what happened may run. */
+export declare const AI_EXPERIMENT_HEADLINE_MAX_CHARS = 280;
+/** How many sentences of detail an explanation may carry. */
+export declare const AI_EXPERIMENT_MAX_POINTS = 4;
+/** How long one of them may run. */
+export declare const AI_EXPERIMENT_POINT_MAX_CHARS = 280;
+/** How long the sentence saying what to do next may run. */
+export declare const AI_EXPERIMENT_NEXT_MAX_CHARS = 280;
+/** An explanation as the model answers it. */
+export interface AiExperimentExplanationAnswer {
+    headline: string;
+    points: string[];
+    /** The variant the answer says won; empty when it names none. */
+    winner: string;
+    next: string;
+}
+/** An explanation as the step keeps it, after the reading has had its say. */
+export interface AiExperimentExplanation {
+    verdict: AiExperimentVerdict;
+    test: string;
+    headline: string;
+    points: string[];
+    /**
+     * The arm the explanation names, which is the arm the READING named: an
+     * answer that named another, or named one where the reading named none, has
+     * had it removed.
+     */
+    winnerId: string | null;
+    next: string;
+    /** What was dropped from the answer, for the log; never shown to a customer. */
+    findings: string[];
+}
+/**
+ * What to do next where the result decided nothing. Code's sentence rather
+ * than the model's: "what next" is where an explanation that may not name a
+ * winner would name one anyway, and the honest answer is the same every time.
+ */
+export declare const AI_EXPERIMENT_NEXT_TOO_EARLY = "Leave the test running until every variant has been shown to enough visitors to compare.";
+export declare const AI_EXPERIMENT_NEXT_INCONCLUSIVE = "These variants are too close to separate. Try a bigger change rather than a longer test.";
+export declare const AI_EXPERIMENT_NEXT_UNREADABLE = "Open the test in A/B testing and check it has a first variant and at least one to compare against it.";
+/** The next step an undecided verdict carries; empty for a decided one, which the answer writes. */
+export declare function aiExperimentNextStep(verdict: AiExperimentVerdict): string;
+/**
+ * The model's explanation held to the reading (AGL-2914).
+ *
+ * The reading decided the verdict; this decides what may be said about it.
+ * Where the reading found no winner, the named arm is removed and any sentence
+ * that claims one is dropped — not softened, dropped, because a hedge in front
+ * of a claim still reads as the claim. Where it found one, the answer may only
+ * name THAT arm; another is removed as well.
+ *
+ * An explanation left with no headline is no explanation, and the step fails
+ * rather than showing an empty card.
+ */
+export declare function checkAiExperimentExplanation(answer: AiExperimentExplanationAnswer | null, reading: AiExperimentReading): AiExperimentExplanation | null;
+/**
+ * The fields a target's variant fills. An email varies its subject line, its
+ * preheader and its body; a screen or a section varies the copy on it. A
+ * variant that fills the other target's fields is answering a different
+ * question, and those fields are dropped.
+ */
+export declare function aiExperimentVariantFields(target: AiExperimentTarget): Array<keyof AiExperimentVariantProposal>;
+/**
+ * A variants answer, held to what the A/B testing card can store (AGL-2914):
+ * between two and four variants, each with copy for the target under test,
+ * none repeating another's copy, and no markup anywhere — the card's fields
+ * are plain text and the besigner writes the elements.
+ *
+ * Returns the proposal with what could not be kept removed, or `null` when
+ * nothing usable is left.
+ */
+export declare function checkAiExperimentVariants(answer: AiExperimentVariantsProposal | null, target: AiExperimentTarget): {
+    proposal: AiExperimentVariantsProposal;
+    findings: string[];
+} | null;