@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/runtime/ai-template-examples.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/runtime/ai-template-examples.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  STARTER_TEMPLATES,\n  type StarterTemplate,\n} from '@aglyn/aglyn/app-utils/starter-templates'\nimport { CANVAS_ROOT_ELEMENT_ID } from '@aglyn/aglyn/foundation/constants/canvas'\nimport {\n  validateAiDoctrineTree,\n  type AiDoctrineNode,\n  type AiDoctrineTree,\n} from './ai-doctrine-validators'\nimport { isHeadlineVariant } from './ai-palette'\nimport { AI_PALETTE, AI_SURFACES } from './ai-palette.generated'\nimport type { AiSystemBlock } from './ai-runtime'\n\n/**\n * The page examples a template generation is shown (AGL-2909): pages from\n * the platform's own starter sites (`STARTER_TEMPLATES`), in the node-map\n * shape the tool takes, as one cached block that is the same bytes for every\n * org.\n *\n * Three things about a starter predate the building rules, and every example\n * is brought up to them the same way rather than shown as it stands:\n *\n * - HEADINGS. A starter picks a heading's look with its variant, and rule 11\n *   reads its level from the element. The page's first heading renders as\n *   its h1, each later one as an h2, and a sixth-level subtitle as a\n *   paragraph.\n * - FORMS. A starter draws its contact form inline, and rule 3 places a form\n *   built on the Forms page by id, so the form is left out.\n * - LINKS. A starter's call to action points nowhere until a member picks\n *   where it goes, and rule 10 refuses a Button or a Screen Link with no\n *   destination (AGL-3072), so such a link is left out.\n *\n * Only props the palette declares are kept, since the model is held to the\n * same palette, and none that holds a px, rem or em length, which rule 5\n * names as a length never to write. A page that still breaks a rule, that\n * the palette validator would change in any way, or that places an element\n * the page surface does not offer (a commerce block) is not shown, and two\n * pages of one shape are shown once: an example the model imitates is one\n * the doctrine accepts exactly as written.\n */\n\nexport interface AiTemplateExample {\n  /** The starter site's name. */\n  starter: string\n  /** The page's name within it. */\n  page: string\n  tree: AiDoctrineTree\n}\n\n/** The block's ceiling: 1,500 tokens at four characters a token. */\nexport const AI_TEMPLATE_EXAMPLES_MAX_CHARS = 6_000\n\nconst FORM_COMPONENTS = new Set(['form', 'formField'])\n\n/** The elements a page links with, which go where their `screenId` or `href` says. */\nconst LINK_COMPONENTS = new Set(['muiButton', 'muiScreenLink'])\n\n/** Whether a starter node is a link that names nowhere to go. */\nfunction linksNowhere(componentId: string, props: Record<string, unknown> | undefined): boolean {\n  if (!LINK_COMPONENTS.has(componentId)) return false\n  const named = (value: unknown) => typeof value === 'string' && value.trim() !== ''\n  return !named(props?.['screenId']) && !named(props?.['href'])\n}\n\n/** A CSS length in the units rule 5 forbids. */\nconst CSS_LENGTH = /\\d(?:\\.\\d+)?(?:px|rem|em)\\b/i\n\ntype StarterNode = {\n  componentId?: string\n  props?: Record<string, unknown>\n  sx?: Record<string, unknown>\n  nodes?: unknown\n}\n\n/** A starter page as the tool's node map, brought up to the rules above; `null` when it cannot be shown. */\nexport function aiStarterExampleTree(nodes: Record<string, StarterNode>): AiDoctrineTree | null {\n  if (!nodes[CANVAS_ROOT_ELEMENT_ID]) return null\n  const allowed = new Set(AI_SURFACES.screen.allow)\n  const out: Record<string, AiDoctrineNode> = {}\n  let headings = 0\n  let unavailable = false\n  const visit = (id: string): string | null => {\n    const node = nodes[id]\n    const componentId = String(node?.componentId ?? '')\n    if (!node || FORM_COMPONENTS.has(componentId) || linksNowhere(componentId, node.props)) return null\n    const root = id === CANVAS_ROOT_ELEMENT_ID\n    if (!root && !allowed.has(componentId)) {\n      unavailable = true\n      return null\n    }\n    // Inserted before the children, so the map reads top-down.\n    const shaped: AiDoctrineNode = { componentId: root ? 'div' : componentId }\n    out[id] = shaped\n    const declared = AI_PALETTE[componentId]?.propsSchema.properties ?? {}\n    const props: Record<string, unknown> = {}\n    for (const [name, value] of Object.entries(node.props ?? {})) {\n      if (!declared[name] || value === undefined) continue\n      if (typeof value === 'string' && CSS_LENGTH.test(value)) continue\n      props[name] = value\n    }\n    if (componentId === 'muiTypography') {\n      const variant = props['variant']\n      if (variant === 'h6') props['component'] = 'p'\n      else if (isHeadlineVariant(variant)) props['component'] = headings++ === 0 ? 'h1' : 'h2'\n    }\n    if (Object.keys(props).length) shaped.props = props\n    if (node.sx && Object.keys(node.sx).length) shaped.sx = node.sx\n    const children = (Array.isArray(node.nodes) ? (node.nodes as unknown[]) : [])\n      .map((child) => (typeof child === 'string' ? visit(child) : null))\n      .filter((child): child is string => child !== null)\n    if (children.length) shaped.nodes = children\n    return id\n  }\n  visit(CANVAS_ROOT_ELEMENT_ID)\n  return unavailable ? null : { rootId: CANVAS_ROOT_ELEMENT_ID, nodes: out }\n}\n\n/** A tree's element structure without its copy or ids, to show one shape once. */\nfunction shapeOf(tree: AiDoctrineTree, id = tree.rootId): string {\n  const node = tree.nodes[id]\n  return `${node.componentId}(${(node.nodes ?? []).map((child) => shapeOf(tree, child)).join(',')})`\n}\n\n/** Every starter page the doctrine accepts as a template exactly as the example shows it. */\nexport function aiStarterTemplateExamples(\n  starters: readonly StarterTemplate[] = STARTER_TEMPLATES,\n): AiTemplateExample[] {\n  const examples: AiTemplateExample[] = []\n  const shapes = new Set<string>()\n  for (const starter of starters) {\n    for (const screen of starter.screens) {\n      const tree = aiStarterExampleTree(screen.nodes as Record<string, StarterNode>)\n      if (!tree) continue\n      const report = validateAiDoctrineTree(tree, 'template')\n      if (!report.ok || !report.tree || report.tree.repairs.length) continue\n      const shape = shapeOf(tree)\n      if (shapes.has(shape)) continue\n      shapes.add(shape)\n      examples.push({ starter: starter.displayName, page: screen.displayName, tree })\n    }\n  }\n  return examples\n}\n\nexport const AI_TEMPLATE_EXAMPLES_PREAMBLE = [\n  'Examples: pages from the platform’s starter sites, in the node-map shape the tool takes.',\n  'Build the way they are built: each band a Container at a stock width (xl for a marketing band, lg for an interactive one, md for prose) with vertical padding on the spacing scale, its content in a Stack, and one h1 for the page.',\n  'Their copy is the starter’s own; a template binds its subject’s tokens wherever a record’s own words, links or pictures go.',\n].join(' ')\n\n/** The examples as one cached system block, held to its ceiling an example at a time. */\nexport function aiTemplateExamplesBlock(\n  examples: readonly AiTemplateExample[] = aiStarterTemplateExamples(),\n): AiSystemBlock {\n  const parts = [AI_TEMPLATE_EXAMPLES_PREAMBLE]\n  let used = AI_TEMPLATE_EXAMPLES_PREAMBLE.length\n  for (const example of examples) {\n    const text = `Starter \"${example.starter}\", page \"${example.page}\":\\n${JSON.stringify(example.tree)}`\n    if (used + text.length + 2 > AI_TEMPLATE_EXAMPLES_MAX_CHARS) continue\n    parts.push(text)\n    used += text.length + 2\n  }\n  return { text: parts.join('\\n\\n'), cacheBreakpoint: true }\n}\n\nlet examplesBlock: AiSystemBlock | null = null\n\n/** The block a template generation sends, built once per process from the starters. */\nexport function aiTemplateExamplesSystemBlock(): AiSystemBlock {\n  examplesBlock ??= aiTemplateExamplesBlock()\n  return examplesBlock\n}\n"],"names":["STARTER_TEMPLATES","CANVAS_ROOT_ELEMENT_ID","validateAiDoctrineTree","isHeadlineVariant","AI_PALETTE","AI_SURFACES","AI_TEMPLATE_EXAMPLES_MAX_CHARS","FORM_COMPONENTS","Set","LINK_COMPONENTS","linksNowhere","componentId","props","has","named","value","trim","CSS_LENGTH","aiStarterExampleTree","nodes","allowed","screen","allow","out","headings","unavailable","visit","id","node","String","root","shaped","declared","propsSchema","properties","name","Object","entries","undefined","test","variant","keys","length","sx","children","Array","isArray","map","child","filter","rootId","shapeOf","tree","join","aiStarterTemplateExamples","starters","examples","shapes","starter","screens","report","ok","repairs","shape","add","push","displayName","page","AI_TEMPLATE_EXAMPLES_PREAMBLE","aiTemplateExamplesBlock","parts","used","example","text","JSON","stringify","cacheBreakpoint","examplesBlock","aiTemplateExamplesSystemBlock"],"mappings":"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"}

package/src/lib/runtime/assist-answer-cache.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @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.
+ */
+export interface AssistCachedAnswer {
+    answer: string;
+    docs: {
+        title: string;
+        url: string;
+    }[];
+    /** Epoch ms the entry was written. */
+    at: number;
+}
+export interface AssistAnswerCacheInputs {
+    question: string;
+    /** 'free' or 'entitled' — different capability levels, different answers. */
+    tier: string;
+    /** The console route the question was asked from ('' when none). */
+    route: string;
+    /** The serving model id. */
+    model: string;
+    /** The product name the assistant answers under (white-label aware). */
+    productName: string;
+}
+/**
+ * Normalise a question so trivially different phrasings share an entry.
+ *
+ * Case, surrounding whitespace, internal runs of whitespace and trailing
+ * punctuation only. Deliberately NOT stemming, stop-word removal or token
+ * sorting: those would make "how do I turn OFF maintenance mode" and "how do
+ * I turn ON maintenance mode" the same key, and serving one for the other is
+ * a wrong answer rather than a missed saving. A cache key may only ever
+ * collapse differences that cannot change the answer.
+ */
+export declare function normaliseAssistQuestion(question: string): string;
+/**
+ * The cache key: a hash over EVERY input that can change the answer.
+ *
+ * Joined on {@link CACHE_KEY_DELIMITER}, which no part can contain.
+ */
+export declare function assistAnswerCacheKey(inputs: AssistAnswerCacheInputs): string;
+/** Whether an entry is still inside the freshness window. */
+export declare function assistCacheEntryIsFresh(entry: AssistCachedAnswer | null | undefined, now?: number): boolean;
+/**
+ * Read one cached answer, or `null`.
+ *
+ * Never throws: a cache is an optimisation, and an unavailable one must cost
+ * a model call rather than the user's answer. The caller therefore cannot
+ * tell a miss from an outage, which is correct — both mean "call the model".
+ */
+export declare function readAssistAnswerCache(firestore: FirebaseFirestore.Firestore, orgId: string, key: string, now?: number): Promise<AssistCachedAnswer | null>;
+/**
+ * Store one answer, pruning the document back to {@link MAX_CACHE_ENTRIES}.
+ *
+ * Read-then-write rather than a blind merging set, because pruning needs to
+ * see what is already there. Not a transaction: two concurrent writers can
+ * lose one entry to each other, and losing a cache entry costs one model call
+ * later — a transaction would cost a contended write on every escalation to
+ * prevent that. The counters this module must never race are in
+ * `reserveAssistMessage`, and none of them are here.
+ *
+ * Never throws, for the same reason the read does not.
+ */
+export declare function writeAssistAnswerCache(firestore: FirebaseFirestore.Firestore, orgId: string, key: string, value: Omit<AssistCachedAnswer, 'at'>, now?: number): Promise<void>;
+/** Exported for the spec — the bound the pruning enforces. */
+export declare const ASSIST_ANSWER_CACHE_LIMIT = 60;
+/** Exported for the spec — the freshness window in ms. */
+export declare const ASSIST_ANSWER_CACHE_TTL_MS: number;

package/src/lib/runtime/assist-answer-cache.js

@@ -0,0 +1,184 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { createHash } from "node:crypto";
+/**
+ * The answer cache for Aglyn Assist escalations (AGL-2486).
+ *
+ * An identical question asked twice must not buy two completions. Retrieval
+ * deflection already takes most of the repeats — the questions people ask over
+ * and over are exactly the ones the documentation answers — so what reaches
+ * here is the residue: the docs-shaped questions retrieval was not confident
+ * enough about, asked again a week later in the same words. The yield is
+ * therefore modest by construction, and saying so is the honest framing: this
+ * is the second lever, not the first.
+ *
+ * ## Scoped to ONE workspace, deliberately
+ *
+ * A cross-tenant cache would hit far more often, and it is the wrong trade.
+ * An entitled answer is composed against that workspace's own name, plan and
+ * current screen, and every deployment can carry white-label orgs whose
+ * assistant answers under their own product name. Sharing an entry between
+ * two workspaces means one workspace's facts reaching the other's panel the
+ * first time a key collides, and a cache is the last place anyone looks for
+ * that. `orgs/{orgId}/…` makes it impossible rather than unlikely.
+ *
+ * The key still carries every input that varies the answer — see
+ * {@link assistAnswerCacheKey}. Scoping alone is not enough: within one
+ * workspace a free member and a Pro member get different capability levels,
+ * and two people on different screens get different guidance.
+ *
+ * ## One document, self-pruning — and why not a TTL
+ *
+ * Entries live in a single `counters/assistAnswerCache` document as a map,
+ * pruned to {@link MAX_CACHE_ENTRIES} newest on every write. That shape was
+ * chosen against a per-document collection with a TTL field, which is the
+ * more obvious design and the worse one here:
+ *
+ * - A Firestore TTL policy is MANUAL gcloud configuration, not repo state
+ *   (see `docs/FIRESTORE_MANUAL_CONFIG.md`). A new collection that assumes one
+ *   grows without bound on every deployment where nobody ran the command —
+ *   including every self-hoster, none of whom will know it exists.
+ * - Pruning on write needs no policy, no index and no operator step, and it
+ *   bounds the document on the deployment that is actually using it.
+ *
+ * Write contention is the cost, and it is affordable: escalations are bounded
+ * by the message caps (ten a day free, a thousand a month entitled), which is
+ * orders of magnitude under the per-document write ceiling.
+ *
+ * ## Staleness
+ *
+ * An entry expires after {@link CACHE_TTL_MS}. The bound exists because the
+ * product moves: an answer describing a screen that has since been rebuilt is
+ * worse than no cache, and unlike a docs deflection there is no live citation
+ * for the user to check it against. Expiry is evaluated on READ as well as
+ * pruned on write, so a stale entry cannot be served by a deployment that has
+ * stopped writing.
+ */ /** Cached answers kept per workspace. */ const MAX_CACHE_ENTRIES = 60;
+/**
+ * How long a cached answer may be served — seven days.
+ *
+ * Long enough that a question asked on Monday and again the following Monday
+ * hits, which is the recurrence pattern this exists for; short enough that an
+ * answer never outlives a release cycle by much. The failure it bounds is an
+ * answer that was right when it was written and is now confidently describing
+ * a screen that changed.
+ */ const CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+/** One doc per org, beside the other `counters/*` documents. */ const CACHE_DOC = 'assistAnswerCache';
+/**
+ * Normalise a question so trivially different phrasings share an entry.
+ *
+ * Case, surrounding whitespace, internal runs of whitespace and trailing
+ * punctuation only. Deliberately NOT stemming, stop-word removal or token
+ * sorting: those would make "how do I turn OFF maintenance mode" and "how do
+ * I turn ON maintenance mode" the same key, and serving one for the other is
+ * a wrong answer rather than a missed saving. A cache key may only ever
+ * collapse differences that cannot change the answer.
+ */ export function normaliseAssistQuestion(question) {
+    return String(question != null ? question : '').toLowerCase().replace(/\s+/g, ' ').replace(/[\s?!.,;:]+$/g, '').trim();
+}
+/**
+ * The delimiter the key parts are joined on: NUL, written as an ESCAPE rather
+ * than as a literal byte.
+ *
+ * NUL because it is the one character that cannot appear in a question, a
+ * route, a model id or a product name, so no pair of different inputs can
+ * concatenate into the same string — the classic way a hashed composite key
+ * develops collisions that read as cache bugs.
+ *
+ * As an escape because a literal NUL in the source makes git classify the
+ * whole file as BINARY: no diff, no review, no blame. It shipped that way once
+ * and the commit carried `Bin 0 -> 9601 bytes` where the file should have been.
+ */ const CACHE_KEY_DELIMITER = '\u0000';
+/**
+ * The cache key: a hash over EVERY input that can change the answer.
+ *
+ * Joined on {@link CACHE_KEY_DELIMITER}, which no part can contain.
+ */ export function assistAnswerCacheKey(inputs) {
+    var _inputs_tier, _inputs_route, _inputs_model, _inputs_productName;
+    const parts = [
+        normaliseAssistQuestion(inputs.question),
+        String((_inputs_tier = inputs.tier) != null ? _inputs_tier : ''),
+        String((_inputs_route = inputs.route) != null ? _inputs_route : ''),
+        String((_inputs_model = inputs.model) != null ? _inputs_model : ''),
+        String((_inputs_productName = inputs.productName) != null ? _inputs_productName : '')
+    ];
+    return createHash('sha256').update(parts.join(CACHE_KEY_DELIMITER)).digest('hex').slice(0, 32);
+}
+/** Whether an entry is still inside the freshness window. */ export function assistCacheEntryIsFresh(entry, now = Date.now()) {
+    if (!entry || typeof entry.answer !== 'string' || !entry.answer) return false;
+    const at = Number(entry.at);
+    // `strictNullChecks` is off repo-wide, so a missing `at` reads as NaN rather
+    // than failing a null check. NaN fails every comparison, which is the right
+    // way round: an entry that cannot say when it was written is not fresh.
+    if (!Number.isFinite(at)) return false;
+    return now - at < CACHE_TTL_MS;
+}
+/**
+ * Read one cached answer, or `null`.
+ *
+ * Never throws: a cache is an optimisation, and an unavailable one must cost
+ * a model call rather than the user's answer. The caller therefore cannot
+ * tell a miss from an outage, which is correct — both mean "call the model".
+ */ export async function readAssistAnswerCache(firestore, orgId, key, now = Date.now()) {
+    try {
+        const snapshot = await firestore.collection('orgs').doc(orgId).collection('counters').doc(CACHE_DOC).get();
+        const entry = snapshot.get(key);
+        return assistCacheEntryIsFresh(entry, now) ? entry : null;
+    } catch (error) {
+        console.error('assist answer cache read failed', error);
+        return null;
+    }
+}
+/**
+ * Store one answer, pruning the document back to {@link MAX_CACHE_ENTRIES}.
+ *
+ * Read-then-write rather than a blind merging set, because pruning needs to
+ * see what is already there. Not a transaction: two concurrent writers can
+ * lose one entry to each other, and losing a cache entry costs one model call
+ * later — a transaction would cost a contended write on every escalation to
+ * prevent that. The counters this module must never race are in
+ * `reserveAssistMessage`, and none of them are here.
+ *
+ * Never throws, for the same reason the read does not.
+ */ export async function writeAssistAnswerCache(firestore, orgId, key, value, now = Date.now()) {
+    try {
+        var _snapshot_data, _value_docs;
+        const ref = firestore.collection('orgs').doc(orgId).collection('counters').doc(CACHE_DOC);
+        const snapshot = await ref.get();
+        const existing = (_snapshot_data = snapshot.data()) != null ? _snapshot_data : {};
+        const next = _extends({}, existing, {
+            [key]: {
+                answer: value.answer,
+                docs: (_value_docs = value.docs) != null ? _value_docs : [],
+                at: now
+            }
+        });
+        const fresh = Object.entries(next).filter(([, entry])=>assistCacheEntryIsFresh(entry, now));
+        fresh.sort((a, b)=>Number(b[1].at) - Number(a[1].at));
+        // A full `set` without merge, so pruning actually REMOVES entries. A
+        // merging set can only ever add: the document would keep every key it had
+        // and the cap would be a comment. This is the one place a non-merging
+        // write is correct, and it is safe only because nothing else writes here.
+        await ref.set(Object.fromEntries(fresh.slice(0, MAX_CACHE_ENTRIES)));
+    } catch (error) {
+        console.error('assist answer cache write failed', error);
+    }
+}
+/** Exported for the spec — the bound the pruning enforces. */ export const ASSIST_ANSWER_CACHE_LIMIT = MAX_CACHE_ENTRIES;
+/** Exported for the spec — the freshness window in ms. */ export const ASSIST_ANSWER_CACHE_TTL_MS = CACHE_TTL_MS;
+
+//# sourceMappingURL=assist-answer-cache.js.map

package/src/lib/runtime/assist-answer-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/runtime/assist-answer-cache.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 { createHash } from 'node:crypto'\n\n/**\n * The answer cache for Aglyn Assist escalations (AGL-2486).\n *\n * An identical question asked twice must not buy two completions. Retrieval\n * deflection already takes most of the repeats — the questions people ask over\n * and over are exactly the ones the documentation answers — so what reaches\n * here is the residue: the docs-shaped questions retrieval was not confident\n * enough about, asked again a week later in the same words. The yield is\n * therefore modest by construction, and saying so is the honest framing: this\n * is the second lever, not the first.\n *\n * ## Scoped to ONE workspace, deliberately\n *\n * A cross-tenant cache would hit far more often, and it is the wrong trade.\n * An entitled answer is composed against that workspace's own name, plan and\n * current screen, and every deployment can carry white-label orgs whose\n * assistant answers under their own product name. Sharing an entry between\n * two workspaces means one workspace's facts reaching the other's panel the\n * first time a key collides, and a cache is the last place anyone looks for\n * that. `orgs/{orgId}/…` makes it impossible rather than unlikely.\n *\n * The key still carries every input that varies the answer — see\n * {@link assistAnswerCacheKey}. Scoping alone is not enough: within one\n * workspace a free member and a Pro member get different capability levels,\n * and two people on different screens get different guidance.\n *\n * ## One document, self-pruning — and why not a TTL\n *\n * Entries live in a single `counters/assistAnswerCache` document as a map,\n * pruned to {@link MAX_CACHE_ENTRIES} newest on every write. That shape was\n * chosen against a per-document collection with a TTL field, which is the\n * more obvious design and the worse one here:\n *\n * - A Firestore TTL policy is MANUAL gcloud configuration, not repo state\n *   (see `docs/FIRESTORE_MANUAL_CONFIG.md`). A new collection that assumes one\n *   grows without bound on every deployment where nobody ran the command —\n *   including every self-hoster, none of whom will know it exists.\n * - Pruning on write needs no policy, no index and no operator step, and it\n *   bounds the document on the deployment that is actually using it.\n *\n * Write contention is the cost, and it is affordable: escalations are bounded\n * by the message caps (ten a day free, a thousand a month entitled), which is\n * orders of magnitude under the per-document write ceiling.\n *\n * ## Staleness\n *\n * An entry expires after {@link CACHE_TTL_MS}. The bound exists because the\n * product moves: an answer describing a screen that has since been rebuilt is\n * worse than no cache, and unlike a docs deflection there is no live citation\n * for the user to check it against. Expiry is evaluated on READ as well as\n * pruned on write, so a stale entry cannot be served by a deployment that has\n * stopped writing.\n */\n\n/** Cached answers kept per workspace. */\nconst MAX_CACHE_ENTRIES = 60\n\n/**\n * How long a cached answer may be served — seven days.\n *\n * Long enough that a question asked on Monday and again the following Monday\n * hits, which is the recurrence pattern this exists for; short enough that an\n * answer never outlives a release cycle by much. The failure it bounds is an\n * answer that was right when it was written and is now confidently describing\n * a screen that changed.\n */\nconst CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000\n\n/** One doc per org, beside the other `counters/*` documents. */\nconst CACHE_DOC = 'assistAnswerCache'\n\nexport interface AssistCachedAnswer {\n  answer: string\n  docs: { title: string; url: string }[]\n  /** Epoch ms the entry was written. */\n  at: number\n}\n\nexport interface AssistAnswerCacheInputs {\n  question: string\n  /** 'free' or 'entitled' — different capability levels, different answers. */\n  tier: string\n  /** The console route the question was asked from ('' when none). */\n  route: string\n  /** The serving model id. */\n  model: string\n  /** The product name the assistant answers under (white-label aware). */\n  productName: string\n}\n\n/**\n * Normalise a question so trivially different phrasings share an entry.\n *\n * Case, surrounding whitespace, internal runs of whitespace and trailing\n * punctuation only. Deliberately NOT stemming, stop-word removal or token\n * sorting: those would make \"how do I turn OFF maintenance mode\" and \"how do\n * I turn ON maintenance mode\" the same key, and serving one for the other is\n * a wrong answer rather than a missed saving. A cache key may only ever\n * collapse differences that cannot change the answer.\n */\nexport function normaliseAssistQuestion(question: string): string {\n  return String(question ?? '')\n    .toLowerCase()\n    .replace(/\\s+/g, ' ')\n    .replace(/[\\s?!.,;:]+$/g, '')\n    .trim()\n}\n\n/**\n * The delimiter the key parts are joined on: NUL, written as an ESCAPE rather\n * than as a literal byte.\n *\n * NUL because it is the one character that cannot appear in a question, a\n * route, a model id or a product name, so no pair of different inputs can\n * concatenate into the same string — the classic way a hashed composite key\n * develops collisions that read as cache bugs.\n *\n * As an escape because a literal NUL in the source makes git classify the\n * whole file as BINARY: no diff, no review, no blame. It shipped that way once\n * and the commit carried `Bin 0 -> 9601 bytes` where the file should have been.\n */\nconst CACHE_KEY_DELIMITER = '\\u0000'\n\n/**\n * The cache key: a hash over EVERY input that can change the answer.\n *\n * Joined on {@link CACHE_KEY_DELIMITER}, which no part can contain.\n */\nexport function assistAnswerCacheKey(inputs: AssistAnswerCacheInputs): string {\n  const parts = [\n    normaliseAssistQuestion(inputs.question),\n    String(inputs.tier ?? ''),\n    String(inputs.route ?? ''),\n    String(inputs.model ?? ''),\n    String(inputs.productName ?? ''),\n  ]\n  return createHash('sha256')\n    .update(parts.join(CACHE_KEY_DELIMITER))\n    .digest('hex')\n    .slice(0, 32)\n}\n\n/** Whether an entry is still inside the freshness window. */\nexport function assistCacheEntryIsFresh(\n  entry: AssistCachedAnswer | null | undefined,\n  now = Date.now(),\n): boolean {\n  if (!entry || typeof entry.answer !== 'string' || !entry.answer) return false\n  const at = Number(entry.at)\n  // `strictNullChecks` is off repo-wide, so a missing `at` reads as NaN rather\n  // than failing a null check. NaN fails every comparison, which is the right\n  // way round: an entry that cannot say when it was written is not fresh.\n  if (!Number.isFinite(at)) return false\n  return now - at < CACHE_TTL_MS\n}\n\n/**\n * Read one cached answer, or `null`.\n *\n * Never throws: a cache is an optimisation, and an unavailable one must cost\n * a model call rather than the user's answer. The caller therefore cannot\n * tell a miss from an outage, which is correct — both mean \"call the model\".\n */\nexport async function readAssistAnswerCache(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  key: string,\n  now = Date.now(),\n): Promise<AssistCachedAnswer | null> {\n  try {\n    const snapshot = await firestore\n      .collection('orgs')\n      .doc(orgId)\n      .collection('counters')\n      .doc(CACHE_DOC)\n      .get()\n    const entry = snapshot.get(key) as AssistCachedAnswer | undefined\n    return assistCacheEntryIsFresh(entry, now) ? entry : null\n  } catch (error) {\n    console.error('assist answer cache read failed', error)\n    return null\n  }\n}\n\n/**\n * Store one answer, pruning the document back to {@link MAX_CACHE_ENTRIES}.\n *\n * Read-then-write rather than a blind merging set, because pruning needs to\n * see what is already there. Not a transaction: two concurrent writers can\n * lose one entry to each other, and losing a cache entry costs one model call\n * later — a transaction would cost a contended write on every escalation to\n * prevent that. The counters this module must never race are in\n * `reserveAssistMessage`, and none of them are here.\n *\n * Never throws, for the same reason the read does not.\n */\nexport async function writeAssistAnswerCache(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  key: string,\n  value: Omit<AssistCachedAnswer, 'at'>,\n  now = Date.now(),\n): Promise<void> {\n  try {\n    const ref = firestore\n      .collection('orgs')\n      .doc(orgId)\n      .collection('counters')\n      .doc(CACHE_DOC)\n    const snapshot = await ref.get()\n    const existing = (snapshot.data() ?? {}) as Record<\n      string,\n      AssistCachedAnswer\n    >\n    const next: Record<string, AssistCachedAnswer> = {\n      ...existing,\n      [key]: { answer: value.answer, docs: value.docs ?? [], at: now },\n    }\n    const fresh = Object.entries(next).filter(([, entry]) =>\n      assistCacheEntryIsFresh(entry, now),\n    )\n    fresh.sort((a, b) => Number(b[1].at) - Number(a[1].at))\n    // A full `set` without merge, so pruning actually REMOVES entries. A\n    // merging set can only ever add: the document would keep every key it had\n    // and the cap would be a comment. This is the one place a non-merging\n    // write is correct, and it is safe only because nothing else writes here.\n    await ref.set(Object.fromEntries(fresh.slice(0, MAX_CACHE_ENTRIES)))\n  } catch (error) {\n    console.error('assist answer cache write failed', error)\n  }\n}\n\n/** Exported for the spec — the bound the pruning enforces. */\nexport const ASSIST_ANSWER_CACHE_LIMIT = MAX_CACHE_ENTRIES\n/** Exported for the spec — the freshness window in ms. */\nexport const ASSIST_ANSWER_CACHE_TTL_MS = CACHE_TTL_MS\n"],"names":["createHash","MAX_CACHE_ENTRIES","CACHE_TTL_MS","CACHE_DOC","normaliseAssistQuestion","question","String","toLowerCase","replace","trim","CACHE_KEY_DELIMITER","assistAnswerCacheKey","inputs","parts","tier","route","model","productName","update","join","digest","slice","assistCacheEntryIsFresh","entry","now","Date","answer","at","Number","isFinite","readAssistAnswerCache","firestore","orgId","key","snapshot","collection","doc","get","error","console","writeAssistAnswerCache","value","ref","existing","data","next","docs","fresh","Object","entries","filter","sort","a","b","set","fromEntries","ASSIST_ANSWER_CACHE_LIMIT","ASSIST_ANSWER_CACHE_TTL_MS"],"mappings":"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"}

package/src/lib/runtime/seo-audit.d.ts

@@ -0,0 +1,93 @@
+/**
+ * @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 { AiSeoAuditReport, AiSeoContentFix } from '../model/ai-seo';
+import type { AiSeoPageFacts } from './seo-page-facts';
+/**
+ * The site SEO audit's scoring (AGL-2910): every audited page held to what a
+ * search result and a crawler need, with nothing asked of a model. Pure, so
+ * the audit is proved against fixtures and a job only spends tokens on the
+ * fixes it cannot make without writing.
+ *
+ * Per page: a title and a description of its own, within their lengths and
+ * used on no other page; one main heading that says something; a description
+ * on every image; a link from somewhere else on the site; and the target
+ * keywords a person named, reported where the page already says them.
+ * Per site: whether search engines are told to stay away, whether the
+ * structured data names and describes the publisher, and whether agents get
+ * guidance of the author's own.
+ *
+ * Keyword coverage is reported, never forced. A page that does not say a
+ * keyword is told so; the fix a job proposes uses the keyword only where the
+ * page is about it, and the listing check refuses a keyword used past its
+ * per-field count.
+ */
+/** Pages one audit covers. A larger site is audited on its first pages by path, and says how many it left. */
+export declare const AI_SEO_AUDIT_MAX_PAGES = 150;
+/** Pages one batch of fixes carries: one model call a batch. */
+export declare const AI_SEO_AUDIT_BATCH_SIZE = 8;
+/** One page as the audit reads it. */
+export interface AiSeoAuditPage {
+    screenId: string;
+    /** The public path, `/` for the home page. */
+    path: string;
+    name: string;
+    versionId: string | null;
+    seo: {
+        title?: string | null;
+        description?: string | null;
+        breadcrumb?: string | null;
+        image?: string | null;
+        imageAlt?: string | null;
+    };
+    /** The screen's own description, which the head falls back to. */
+    description?: string | null;
+    facts: AiSeoPageFacts;
+    /** Whether another audited page or a shared layout links here. */
+    linkedFrom: boolean;
+    keywords: readonly string[];
+}
+/** The site as the audit reads it. */
+export interface AiSeoAuditSite {
+    discouraged: boolean;
+    entity: {
+        name?: string | null;
+        description?: string | null;
+    };
+    agent: {
+        whenToUse?: string | null;
+    };
+}
+/** A path as the keyword lines and the routing map both spell it: leading slash, no trailing one. */
+export declare function aiSeoNormalizePath(path: string): string;
+/**
+ * Target keywords per page, one line a page: `/pricing: plans, pricing`.
+ * A line without a path, or with a path the site does not have, names no
+ * page; the step reports the paths it could not match.
+ */
+export declare function parseAiSeoKeywordLines(raw: unknown): Record<string, string[]>;
+/** Audit the pages and the site; nothing here reads, writes or generates. */
+export declare function aiSeoAudit(pages: readonly AiSeoAuditPage[], site: AiSeoAuditSite, options?: {
+    skipped?: number;
+    batchSize?: number;
+}): AiSeoAuditReport;
+/**
+ * The content fixes that need no model: every main heading after the first
+ * editable one becomes an `h2`, so the page keeps one.
+ */
+export declare function aiSeoHeadingDemotions(facts: AiSeoPageFacts): AiSeoContentFix[];
+/** The queue's batches, in order. */
+export declare function aiSeoAuditBatches(report: Pick<AiSeoAuditReport, 'queue' | 'batchSize'>): string[][];