@aglyn/plugins-ai 1.0.0-beta.230 → 1.0.0-beta.232

package/src/lib/runtime/ai-dev-replay.d.ts

@@ -0,0 +1,116 @@
+/**
+ * @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 { AiProvider, AiProviderRequest, AiResult, AiStreamEvent, AiSystemBlock, AiTool } from '../providers/contract';
+import { type AiDevEnv as Env, type AiDevReplayMode } from './ai-dev-env';
+/**
+ * THE DEVELOPMENT REPLAY CACHE (AGL-3660).
+ *
+ * Almost every dollar the provider bills in a month is a development run: a
+ * live eval, the layout screenshots fed by one, a local guided start. Most of
+ * the requests in a second run of the same eval are byte-identical to the
+ * first — the change under test was to a compiler, a check or one prompt, not
+ * to all of them — and each identical request bought the same sample twice.
+ *
+ * So, outside production only, the runtime keys each request by a hash of
+ * everything that decides the answer — the provider, the model, the system
+ * blocks, the tools, the messages, the ceiling, thinking and effort — and keeps
+ * the provider's answer under `.cache/ai-replay/` (gitignored). The next
+ * identical request is answered from disk for nothing; a request whose prompt
+ * changed by one byte has a new key and goes to the provider. A replayed answer
+ * is a real answer the same model gave to the same bytes, so an eval that
+ * passes on replays has still seen every CHANGED prompt answered live: the
+ * replay never stands in for a prompt the provider has not answered.
+ *
+ * `AGLYN_AI_REPLAY`:
+ *  - `1` / `on`: replay what is recorded, record what is not.
+ *  - `refresh`: every request live, its answer recorded over the old one.
+ *  - `off` / `0`: nothing read, nothing written.
+ *  - unset: on under the live-eval launcher (`AI_EVAL_LIVE_LAUNCHER`), off
+ *    everywhere else, so a dev server or a spec that never asked for it
+ *    behaves exactly as before.
+ *
+ * It never runs in a deployed server. `NODE_ENV=production`, `VERCEL_ENV`
+ * of `production` or `preview`, or a Cloud Run service (`K_SERVICE`) turn it
+ * off whatever the variable says, and the first request says so in the log:
+ * a recorded answer handed to a customer would be another customer's page.
+ *
+ * Every live eval's table carries `aiDevReplayStats()`, so a run that was
+ * all replays reads as one: `live: 0` is not a live pass.
+ */
+/** JSON with every object's keys in sorted order: the same value, the same bytes, whatever built it. */
+export declare function aiCanonicalJson(value: unknown): string;
+/** What a request's answer depends on. The key, the signal and the cache lifetime are not part of it. */
+export interface AiReplayRequest {
+    model: string;
+    system: readonly AiSystemBlock[];
+    messages: AiProviderRequest['messages'];
+    tools?: readonly AiTool[];
+    maxTokens: number;
+    thinking?: AiProviderRequest['thinking'];
+    effort?: AiProviderRequest['effort'];
+}
+/** The request's replay key: a SHA-256 of everything that decides the answer. */
+export declare function aiDevReplayKey(providerId: string, stream: boolean, request: AiReplayRequest): string;
+/**
+ * The prefix a provider caches: the model, the tools and every system block
+ * through the last breakpoint. Two requests with the same prefix key read one
+ * cache entry; `null` when the request marks no breakpoint.
+ */
+export declare function aiCachedPrefixKey(request: Pick<AiReplayRequest, 'model' | 'system' | 'tools'>): string | null;
+/** Where recorded answers are kept. */
+export declare function aiDevReplayDir(env?: Env): string;
+/** How many of this process's requests were sent, and how many were answered from disk. */
+export interface AiDevReplayStats {
+    mode: AiDevReplayMode;
+    /** Requests sent to the provider. */
+    live: number;
+    /** Requests answered from a recording. */
+    replayed: number;
+    /** What the live requests cost at the provider's list rates. */
+    liveProviderUsd: number;
+    /** What the replayed ones would have cost, had they been sent. */
+    savedProviderUsd: number;
+}
+/** This process's count so far: what a live eval prints beside its table. */
+export declare function aiDevReplayStats(env?: Env): AiDevReplayStats;
+/** Starts the count again; a spec that runs two rounds reports each. */
+export declare function resetAiDevReplayStats(): void;
+/** Counts one request a live path sent, at what the provider billed for it; `discount` is a batch's half. */
+export declare function aiDevCountLive(usage: AiResult['usage'], model: string, discount?: number): void;
+/**
+ * One request through the replay cache: answered from disk when recorded and
+ * the mode replays, otherwise sent through `send` and recorded. `send` is the
+ * live path — the provider, or the batch queue — and counts its own spend.
+ */
+export declare function aiDevReplayComplete(provider: Pick<AiProvider, 'id'>, request: AiReplayRequest, mode: Exclude<AiDevReplayMode, 'off'>, send: () => Promise<AiResult>, env?: Env): Promise<AiResult>;
+/** The streaming half of {@link aiDevReplayComplete}. */
+export declare function aiDevReplayStream(provider: Pick<AiProvider, 'id'>, request: AiReplayRequest, mode: Exclude<AiDevReplayMode, 'off'>, send: () => Promise<AsyncIterable<AiStreamEvent>>, env?: Env): Promise<AsyncIterable<AiStreamEvent>>;
+export declare function aiDevWarmPrefixFirst<T>(prefixKey: string | null, ttlMs: number, send: () => Promise<T>, now?: () => number): Promise<T>;
+/** Forgets every warmed prefix; for specs. */
+export declare function resetAiDevWarmPrefixes(): void;
+/**
+ * The line every live eval's table carries (AGL-3660): how many of its
+ * requests went to the provider and how many were answered from disk, what
+ * the live ones cost at list, and how many batches carried them. A table
+ * whose `live` is 0 proved nothing new — every prompt in it had been answered
+ * before — and is not a live pass; `AGLYN_AI_REPLAY=refresh` asks again.
+ */
+export declare function aiLiveRunLedger(env?: Env): AiDevReplayStats & {
+    batches: number;
+    batchedRequests: number;
+    allReplayed: boolean;
+};

package/src/lib/runtime/ai-dev-replay.js

@@ -0,0 +1,313 @@
+import { _ as _async_iterator } from "@swc/helpers/_/_async_iterator";
+import { _ as _await_async_generator } from "@swc/helpers/_/_await_async_generator";
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { _ as _wrap_async_generator } from "@swc/helpers/_/_wrap_async_generator";
+/**
+ * @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";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { estimateAiProviderCostUsd } from "../providers/catalog.js";
+import { aiLiveBatchStats } from "./ai-live-batch.js";
+import { AI_REPLAY_DIR_ENV, aiDevReplayMode } from "./ai-dev-env.js";
+/** The key format's version: bumped when what a key covers changes, so no old answer is read under a new meaning. */ const KEY_VERSION = 1;
+/**
+ * THE DEVELOPMENT REPLAY CACHE (AGL-3660).
+ *
+ * Almost every dollar the provider bills in a month is a development run: a
+ * live eval, the layout screenshots fed by one, a local guided start. Most of
+ * the requests in a second run of the same eval are byte-identical to the
+ * first — the change under test was to a compiler, a check or one prompt, not
+ * to all of them — and each identical request bought the same sample twice.
+ *
+ * So, outside production only, the runtime keys each request by a hash of
+ * everything that decides the answer — the provider, the model, the system
+ * blocks, the tools, the messages, the ceiling, thinking and effort — and keeps
+ * the provider's answer under `.cache/ai-replay/` (gitignored). The next
+ * identical request is answered from disk for nothing; a request whose prompt
+ * changed by one byte has a new key and goes to the provider. A replayed answer
+ * is a real answer the same model gave to the same bytes, so an eval that
+ * passes on replays has still seen every CHANGED prompt answered live: the
+ * replay never stands in for a prompt the provider has not answered.
+ *
+ * `AGLYN_AI_REPLAY`:
+ *  - `1` / `on`: replay what is recorded, record what is not.
+ *  - `refresh`: every request live, its answer recorded over the old one.
+ *  - `off` / `0`: nothing read, nothing written.
+ *  - unset: on under the live-eval launcher (`AI_EVAL_LIVE_LAUNCHER`), off
+ *    everywhere else, so a dev server or a spec that never asked for it
+ *    behaves exactly as before.
+ *
+ * It never runs in a deployed server. `NODE_ENV=production`, `VERCEL_ENV`
+ * of `production` or `preview`, or a Cloud Run service (`K_SERVICE`) turn it
+ * off whatever the variable says, and the first request says so in the log:
+ * a recorded answer handed to a customer would be another customer's page.
+ *
+ * Every live eval's table carries `aiDevReplayStats()`, so a run that was
+ * all replays reads as one: `live: 0` is not a live pass.
+ */ // ── The key ──────────────────────────────────────────────────────────────
+/** JSON with every object's keys in sorted order: the same value, the same bytes, whatever built it. */ export function aiCanonicalJson(value) {
+    return JSON.stringify(sortKeys(value));
+}
+function sortKeys(value) {
+    if (Array.isArray(value)) return value.map(sortKeys);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.keys(value).sort().filter((key)=>value[key] !== undefined).map((key)=>[
+                key,
+                sortKeys(value[key])
+            ]));
+    }
+    return value;
+}
+/** The request's replay key: a SHA-256 of everything that decides the answer. */ export function aiDevReplayKey(providerId, stream, request) {
+    var _request_tools, _request_thinking, _request_effort;
+    return createHash('sha256').update(aiCanonicalJson({
+        v: KEY_VERSION,
+        provider: providerId,
+        stream,
+        model: request.model,
+        // A breakpoint changes no answer, so the key reads the text alone.
+        system: request.system.map((block)=>block.text),
+        tools: (_request_tools = request.tools) != null ? _request_tools : [],
+        messages: request.messages,
+        maxTokens: request.maxTokens,
+        thinking: (_request_thinking = request.thinking) != null ? _request_thinking : null,
+        effort: (_request_effort = request.effort) != null ? _request_effort : null
+    })).digest('hex');
+}
+/**
+ * The prefix a provider caches: the model, the tools and every system block
+ * through the last breakpoint. Two requests with the same prefix key read one
+ * cache entry; `null` when the request marks no breakpoint.
+ */ export function aiCachedPrefixKey(request) {
+    var _request_tools;
+    const last = request.system.map((block)=>Boolean(block.cacheBreakpoint)).lastIndexOf(true);
+    if (last < 0) return null;
+    return createHash('sha256').update(aiCanonicalJson({
+        model: request.model,
+        tools: (_request_tools = request.tools) != null ? _request_tools : [],
+        system: request.system.slice(0, last + 1).map((block)=>block.text)
+    })).digest('hex');
+}
+// ── The store ────────────────────────────────────────────────────────────
+/** The repository root: the nearest directory up from here holding `nx.json`, else the working directory. */ function repositoryRoot(start = process.cwd()) {
+    let dir = start;
+    for(;;){
+        if (existsSync(join(dir, 'nx.json'))) return dir;
+        const parent = dirname(dir);
+        if (parent === dir) return start;
+        dir = parent;
+    }
+}
+/** Where recorded answers are kept. */ export function aiDevReplayDir(env = process.env) {
+    return env[AI_REPLAY_DIR_ENV] || join(repositoryRoot(), '.cache', 'ai-replay');
+}
+function pathFor(dir, key) {
+    return join(dir, key.slice(0, 2), `${key}.json`);
+}
+function readRecording(dir, key) {
+    const path = pathFor(dir, key);
+    if (!existsSync(path)) return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return (parsed == null ? void 0 : parsed.v) === KEY_VERSION && parsed.key === key ? parsed : null;
+    } catch (unused) {
+        return null;
+    }
+}
+function writeRecording(dir, recording) {
+    const path = pathFor(dir, recording.key);
+    mkdirSync(dirname(path), {
+        recursive: true
+    });
+    // Written aside and renamed, so a run killed mid-write leaves no half file to replay.
+    const temp = `${path}.${process.pid}.tmp`;
+    writeFileSync(temp, JSON.stringify(recording));
+    renameSync(temp, path);
+}
+const stats = {
+    mode: 'off',
+    live: 0,
+    replayed: 0,
+    liveProviderUsd: 0,
+    savedProviderUsd: 0
+};
+/** This process's count so far: what a live eval prints beside its table. */ export function aiDevReplayStats(env = process.env) {
+    return _extends({}, stats, {
+        mode: aiDevReplayMode(env),
+        liveProviderUsd: round(stats.liveProviderUsd),
+        savedProviderUsd: round(stats.savedProviderUsd)
+    });
+}
+/** Starts the count again; a spec that runs two rounds reports each. */ export function resetAiDevReplayStats() {
+    stats.live = 0;
+    stats.replayed = 0;
+    stats.liveProviderUsd = 0;
+    stats.savedProviderUsd = 0;
+}
+function round(usd) {
+    return Math.round(usd * 1000000) / 1000000;
+}
+function usageCost(usage, model) {
+    return estimateAiProviderCostUsd(usage, model);
+}
+/** Counts one request a live path sent, at what the provider billed for it; `discount` is a batch's half. */ export function aiDevCountLive(usage, model, discount = 1) {
+    stats.live += 1;
+    stats.liveProviderUsd += usageCost(usage, model) * discount;
+}
+// ── The seam ─────────────────────────────────────────────────────────────
+function replayEvents(events) {
+    return _wrap_async_generator(function*() {
+        for (const event of events)yield event;
+    })();
+}
+/** A live stream passed through as it arrives, and recorded once it is done. */ function recordEvents(source, onDone) {
+    return _wrap_async_generator(function*() {
+        const events = [];
+        let completed = false;
+        {
+            var _iteratorAbruptCompletion = false, _didIteratorError = false, _iteratorError;
+            try {
+                for(var _iterator = _async_iterator(source), _step; _iteratorAbruptCompletion = !(_step = yield _await_async_generator(_iterator.next())).done; _iteratorAbruptCompletion = false){
+                    let _value = _step.value;
+                    const event = _value;
+                    events.push(event);
+                    if (event.type === 'done') completed = true;
+                    yield event;
+                }
+            } catch (err) {
+                _didIteratorError = true;
+                _iteratorError = err;
+            } finally{
+                try {
+                    if (_iteratorAbruptCompletion && _iterator.return != null) {
+                        yield _await_async_generator(_iterator.return());
+                    }
+                } finally{
+                    if (_didIteratorError) {
+                        throw _iteratorError;
+                    }
+                }
+            }
+        }
+        // A stream cut short, or one that carried a provider error, is not an
+        // answer worth keeping: the next run asks again.
+        if (completed && !events.some((event)=>event.type === 'error')) onDone(events);
+    })();
+}
+/**
+ * One request through the replay cache: answered from disk when recorded and
+ * the mode replays, otherwise sent through `send` and recorded. `send` is the
+ * live path — the provider, or the batch queue — and counts its own spend.
+ */ export async function aiDevReplayComplete(provider, request, mode, send, env = process.env) {
+    const dir = aiDevReplayDir(env);
+    const key = aiDevReplayKey(provider.id, false, request);
+    const recorded = mode === 'replay' ? readRecording(dir, key) : null;
+    if ((recorded == null ? void 0 : recorded.kind) === 'result') {
+        stats.replayed += 1;
+        stats.savedProviderUsd += usageCost(recorded.result.usage, request.model);
+        return recorded.result;
+    }
+    const result = await send();
+    writeRecording(dir, {
+        v: KEY_VERSION,
+        key,
+        model: request.model,
+        recordedAt: new Date().toISOString(),
+        kind: 'result',
+        result
+    });
+    return result;
+}
+/** The streaming half of {@link aiDevReplayComplete}. */ export async function aiDevReplayStream(provider, request, mode, send, env = process.env) {
+    const dir = aiDevReplayDir(env);
+    const key = aiDevReplayKey(provider.id, true, request);
+    const recorded = mode === 'replay' ? readRecording(dir, key) : null;
+    if ((recorded == null ? void 0 : recorded.kind) === 'stream') {
+        stats.replayed += 1;
+        const done = recorded.events.find((event)=>event.type === 'done');
+        if ((done == null ? void 0 : done.type) === 'done') stats.savedProviderUsd += usageCost(done.usage, request.model);
+        return replayEvents(recorded.events);
+    }
+    const live = await send();
+    return recordEvents(live, (events)=>{
+        const done = events.find((event)=>event.type === 'done');
+        if ((done == null ? void 0 : done.type) === 'done') aiDevCountLive(done.usage, request.model);
+        writeRecording(dir, {
+            v: KEY_VERSION,
+            key,
+            model: request.model,
+            recordedAt: new Date().toISOString(),
+            kind: 'stream',
+            events
+        });
+    });
+}
+// ── Warming a shared prefix before a fan-out ─────────────────────────────
+/**
+ * A cache entry is readable only once the request that writes it has started
+ * answering, so N requests sent at once over one prefix all pay to write it
+ * and none reads it — which is exactly what a live eval's `Promise.all` over
+ * its briefs did. In a development run the first request over a prefix goes
+ * alone; the others wait for it and then read what it wrote. A prefix
+ * answered within the cache's lifetime is not held again.
+ *
+ * Development only, like everything here: production's beat runs one step at
+ * a time, and holding a customer's request behind another's would trade
+ * their seconds for our cents.
+ */ const warming = new Map();
+const warmedAt = new Map();
+export async function aiDevWarmPrefixFirst(prefixKey, ttlMs, send, now = Date.now) {
+    if (!prefixKey) return send();
+    const warmed = warmedAt.get(prefixKey);
+    if (warmed !== undefined && now() - warmed < ttlMs) return send();
+    const pending = warming.get(prefixKey);
+    if (pending) {
+        await pending.catch(()=>undefined);
+        return send();
+    }
+    const first = send();
+    warming.set(prefixKey, first);
+    try {
+        const result = await first;
+        warmedAt.set(prefixKey, now());
+        return result;
+    } finally{
+        warming.delete(prefixKey);
+    }
+}
+/** Forgets every warmed prefix; for specs. */ export function resetAiDevWarmPrefixes() {
+    warming.clear();
+    warmedAt.clear();
+}
+// ── What a live eval prints ──────────────────────────────────────────────
+/**
+ * The line every live eval's table carries (AGL-3660): how many of its
+ * requests went to the provider and how many were answered from disk, what
+ * the live ones cost at list, and how many batches carried them. A table
+ * whose `live` is 0 proved nothing new — every prompt in it had been answered
+ * before — and is not a live pass; `AGLYN_AI_REPLAY=refresh` asks again.
+ */ export function aiLiveRunLedger(env = process.env) {
+    const replay = aiDevReplayStats(env);
+    const batch = aiLiveBatchStats();
+    return _extends({}, replay, {
+        batches: batch.batches,
+        batchedRequests: batch.requests,
+        allReplayed: replay.live === 0 && replay.replayed > 0
+    });
+}
+
+//# sourceMappingURL=ai-dev-replay.js.map

package/src/lib/runtime/ai-dev-replay.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/runtime/ai-dev-replay.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'\nimport { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'\nimport { dirname, join } from 'node:path'\nimport { estimateAiProviderCostUsd } from '../providers/catalog'\nimport type {\n  AiProvider,\n  AiProviderRequest,\n  AiResult,\n  AiStreamEvent,\n  AiSystemBlock,\n  AiTool,\n} from '../providers/contract'\nimport { aiLiveBatchStats } from './ai-live-batch'\nimport { AI_REPLAY_DIR_ENV, aiDevReplayMode, type AiDevEnv as Env, type AiDevReplayMode } from './ai-dev-env'\n\n/** The key format's version: bumped when what a key covers changes, so no old answer is read under a new meaning. */\nconst KEY_VERSION = 1\n\n/**\n * THE DEVELOPMENT REPLAY CACHE (AGL-3660).\n *\n * Almost every dollar the provider bills in a month is a development run: a\n * live eval, the layout screenshots fed by one, a local guided start. Most of\n * the requests in a second run of the same eval are byte-identical to the\n * first — the change under test was to a compiler, a check or one prompt, not\n * to all of them — and each identical request bought the same sample twice.\n *\n * So, outside production only, the runtime keys each request by a hash of\n * everything that decides the answer — the provider, the model, the system\n * blocks, the tools, the messages, the ceiling, thinking and effort — and keeps\n * the provider's answer under `.cache/ai-replay/` (gitignored). The next\n * identical request is answered from disk for nothing; a request whose prompt\n * changed by one byte has a new key and goes to the provider. A replayed answer\n * is a real answer the same model gave to the same bytes, so an eval that\n * passes on replays has still seen every CHANGED prompt answered live: the\n * replay never stands in for a prompt the provider has not answered.\n *\n * `AGLYN_AI_REPLAY`:\n *  - `1` / `on`: replay what is recorded, record what is not.\n *  - `refresh`: every request live, its answer recorded over the old one.\n *  - `off` / `0`: nothing read, nothing written.\n *  - unset: on under the live-eval launcher (`AI_EVAL_LIVE_LAUNCHER`), off\n *    everywhere else, so a dev server or a spec that never asked for it\n *    behaves exactly as before.\n *\n * It never runs in a deployed server. `NODE_ENV=production`, `VERCEL_ENV`\n * of `production` or `preview`, or a Cloud Run service (`K_SERVICE`) turn it\n * off whatever the variable says, and the first request says so in the log:\n * a recorded answer handed to a customer would be another customer's page.\n *\n * Every live eval's table carries `aiDevReplayStats()`, so a run that was\n * all replays reads as one: `live: 0` is not a live pass.\n */\n\n// ── The key ──────────────────────────────────────────────────────────────\n\n/** JSON with every object's keys in sorted order: the same value, the same bytes, whatever built it. */\nexport function aiCanonicalJson(value: unknown): string {\n  return JSON.stringify(sortKeys(value))\n}\n\nfunction sortKeys(value: unknown): unknown {\n  if (Array.isArray(value)) return value.map(sortKeys)\n  if (value && typeof value === 'object') {\n    return Object.fromEntries(\n      Object.keys(value as Record<string, unknown>)\n        .sort()\n        .filter((key) => (value as Record<string, unknown>)[key] !== undefined)\n        .map((key) => [key, sortKeys((value as Record<string, unknown>)[key])]),\n    )\n  }\n  return value\n}\n\n/** What a request's answer depends on. The key, the signal and the cache lifetime are not part of it. */\nexport interface AiReplayRequest {\n  model: string\n  system: readonly AiSystemBlock[]\n  messages: AiProviderRequest['messages']\n  tools?: readonly AiTool[]\n  maxTokens: number\n  thinking?: AiProviderRequest['thinking']\n  effort?: AiProviderRequest['effort']\n}\n\n/** The request's replay key: a SHA-256 of everything that decides the answer. */\nexport function aiDevReplayKey(providerId: string, stream: boolean, request: AiReplayRequest): string {\n  return createHash('sha256')\n    .update(\n      aiCanonicalJson({\n        v: KEY_VERSION,\n        provider: providerId,\n        stream,\n        model: request.model,\n        // A breakpoint changes no answer, so the key reads the text alone.\n        system: request.system.map((block) => block.text),\n        tools: request.tools ?? [],\n        messages: request.messages,\n        maxTokens: request.maxTokens,\n        thinking: request.thinking ?? null,\n        effort: request.effort ?? null,\n      }),\n    )\n    .digest('hex')\n}\n\n/**\n * The prefix a provider caches: the model, the tools and every system block\n * through the last breakpoint. Two requests with the same prefix key read one\n * cache entry; `null` when the request marks no breakpoint.\n */\nexport function aiCachedPrefixKey(request: Pick<AiReplayRequest, 'model' | 'system' | 'tools'>): string | null {\n  const last = request.system.map((block) => Boolean(block.cacheBreakpoint)).lastIndexOf(true)\n  if (last < 0) return null\n  return createHash('sha256')\n    .update(\n      aiCanonicalJson({\n        model: request.model,\n        tools: request.tools ?? [],\n        system: request.system.slice(0, last + 1).map((block) => block.text),\n      }),\n    )\n    .digest('hex')\n}\n\n// ── The store ────────────────────────────────────────────────────────────\n\n/** The repository root: the nearest directory up from here holding `nx.json`, else the working directory. */\nfunction repositoryRoot(start: string = process.cwd()): string {\n  let dir = start\n  for (;;) {\n    if (existsSync(join(dir, 'nx.json'))) return dir\n    const parent = dirname(dir)\n    if (parent === dir) return start\n    dir = parent\n  }\n}\n\n/** Where recorded answers are kept. */\nexport function aiDevReplayDir(env: Env = process.env): string {\n  return env[AI_REPLAY_DIR_ENV] || join(repositoryRoot(), '.cache', 'ai-replay')\n}\n\ntype Recording =\n  | { v: number; key: string; model: string; recordedAt: string; kind: 'result'; result: AiResult }\n  | { v: number; key: string; model: string; recordedAt: string; kind: 'stream'; events: AiStreamEvent[] }\n\nfunction pathFor(dir: string, key: string): string {\n  return join(dir, key.slice(0, 2), `${key}.json`)\n}\n\nfunction readRecording(dir: string, key: string): Recording | null {\n  const path = pathFor(dir, key)\n  if (!existsSync(path)) return null\n  try {\n    const parsed = JSON.parse(readFileSync(path, 'utf8')) as Recording\n    return parsed?.v === KEY_VERSION && parsed.key === key ? parsed : null\n  } catch {\n    return null\n  }\n}\n\nfunction writeRecording(dir: string, recording: Recording): void {\n  const path = pathFor(dir, recording.key)\n  mkdirSync(dirname(path), { recursive: true })\n  // Written aside and renamed, so a run killed mid-write leaves no half file to replay.\n  const temp = `${path}.${process.pid}.tmp`\n  writeFileSync(temp, JSON.stringify(recording))\n  renameSync(temp, path)\n}\n\n// ── What a run did ───────────────────────────────────────────────────────\n\n/** How many of this process's requests were sent, and how many were answered from disk. */\nexport interface AiDevReplayStats {\n  mode: AiDevReplayMode\n  /** Requests sent to the provider. */\n  live: number\n  /** Requests answered from a recording. */\n  replayed: number\n  /** What the live requests cost at the provider's list rates. */\n  liveProviderUsd: number\n  /** What the replayed ones would have cost, had they been sent. */\n  savedProviderUsd: number\n}\n\nconst stats: AiDevReplayStats = {\n  mode: 'off',\n  live: 0,\n  replayed: 0,\n  liveProviderUsd: 0,\n  savedProviderUsd: 0,\n}\n\n/** This process's count so far: what a live eval prints beside its table. */\nexport function aiDevReplayStats(env: Env = process.env): AiDevReplayStats {\n  return {\n    ...stats,\n    mode: aiDevReplayMode(env),\n    liveProviderUsd: round(stats.liveProviderUsd),\n    savedProviderUsd: round(stats.savedProviderUsd),\n  }\n}\n\n/** Starts the count again; a spec that runs two rounds reports each. */\nexport function resetAiDevReplayStats(): void {\n  stats.live = 0\n  stats.replayed = 0\n  stats.liveProviderUsd = 0\n  stats.savedProviderUsd = 0\n}\n\nfunction round(usd: number): number {\n  return Math.round(usd * 1_000_000) / 1_000_000\n}\n\nfunction usageCost(usage: AiResult['usage'], model: string): number {\n  return estimateAiProviderCostUsd(usage, model)\n}\n\n/** Counts one request a live path sent, at what the provider billed for it; `discount` is a batch's half. */\nexport function aiDevCountLive(usage: AiResult['usage'], model: string, discount = 1): void {\n  stats.live += 1\n  stats.liveProviderUsd += usageCost(usage, model) * discount\n}\n\n// ── The seam ─────────────────────────────────────────────────────────────\n\nasync function* replayEvents(events: readonly AiStreamEvent[]): AsyncGenerator<AiStreamEvent> {\n  for (const event of events) yield event\n}\n\n/** A live stream passed through as it arrives, and recorded once it is done. */\nasync function* recordEvents(\n  source: AsyncIterable<AiStreamEvent>,\n  onDone: (events: AiStreamEvent[]) => void,\n): AsyncGenerator<AiStreamEvent> {\n  const events: AiStreamEvent[] = []\n  let completed = false\n  for await (const event of source) {\n    events.push(event)\n    if (event.type === 'done') completed = true\n    yield event\n  }\n  // A stream cut short, or one that carried a provider error, is not an\n  // answer worth keeping: the next run asks again.\n  if (completed && !events.some((event) => event.type === 'error')) onDone(events)\n}\n\n/**\n * One request through the replay cache: answered from disk when recorded and\n * the mode replays, otherwise sent through `send` and recorded. `send` is the\n * live path — the provider, or the batch queue — and counts its own spend.\n */\nexport async function aiDevReplayComplete(\n  provider: Pick<AiProvider, 'id'>,\n  request: AiReplayRequest,\n  mode: Exclude<AiDevReplayMode, 'off'>,\n  send: () => Promise<AiResult>,\n  env: Env = process.env,\n): Promise<AiResult> {\n  const dir = aiDevReplayDir(env)\n  const key = aiDevReplayKey(provider.id, false, request)\n  const recorded = mode === 'replay' ? readRecording(dir, key) : null\n  if (recorded?.kind === 'result') {\n    stats.replayed += 1\n    stats.savedProviderUsd += usageCost(recorded.result.usage, request.model)\n    return recorded.result\n  }\n  const result = await send()\n  writeRecording(dir, {\n    v: KEY_VERSION,\n    key,\n    model: request.model,\n    recordedAt: new Date().toISOString(),\n    kind: 'result',\n    result,\n  })\n  return result\n}\n\n/** The streaming half of {@link aiDevReplayComplete}. */\nexport async function aiDevReplayStream(\n  provider: Pick<AiProvider, 'id'>,\n  request: AiReplayRequest,\n  mode: Exclude<AiDevReplayMode, 'off'>,\n  send: () => Promise<AsyncIterable<AiStreamEvent>>,\n  env: Env = process.env,\n): Promise<AsyncIterable<AiStreamEvent>> {\n  const dir = aiDevReplayDir(env)\n  const key = aiDevReplayKey(provider.id, true, request)\n  const recorded = mode === 'replay' ? readRecording(dir, key) : null\n  if (recorded?.kind === 'stream') {\n    stats.replayed += 1\n    const done = recorded.events.find((event) => event.type === 'done')\n    if (done?.type === 'done') stats.savedProviderUsd += usageCost(done.usage, request.model)\n    return replayEvents(recorded.events)\n  }\n  const live = await send()\n  return recordEvents(live, (events) => {\n    const done = events.find((event) => event.type === 'done')\n    if (done?.type === 'done') aiDevCountLive(done.usage, request.model)\n    writeRecording(dir, {\n      v: KEY_VERSION,\n      key,\n      model: request.model,\n      recordedAt: new Date().toISOString(),\n      kind: 'stream',\n      events,\n    })\n  })\n}\n\n// ── Warming a shared prefix before a fan-out ─────────────────────────────\n\n/**\n * A cache entry is readable only once the request that writes it has started\n * answering, so N requests sent at once over one prefix all pay to write it\n * and none reads it — which is exactly what a live eval's `Promise.all` over\n * its briefs did. In a development run the first request over a prefix goes\n * alone; the others wait for it and then read what it wrote. A prefix\n * answered within the cache's lifetime is not held again.\n *\n * Development only, like everything here: production's beat runs one step at\n * a time, and holding a customer's request behind another's would trade\n * their seconds for our cents.\n */\nconst warming = new Map<string, Promise<unknown>>()\nconst warmedAt = new Map<string, number>()\n\nexport async function aiDevWarmPrefixFirst<T>(\n  prefixKey: string | null,\n  ttlMs: number,\n  send: () => Promise<T>,\n  now: () => number = Date.now,\n): Promise<T> {\n  if (!prefixKey) return send()\n  const warmed = warmedAt.get(prefixKey)\n  if (warmed !== undefined && now() - warmed < ttlMs) return send()\n  const pending = warming.get(prefixKey)\n  if (pending) {\n    await pending.catch(() => undefined)\n    return send()\n  }\n  const first = send()\n  warming.set(prefixKey, first)\n  try {\n    const result = await first\n    warmedAt.set(prefixKey, now())\n    return result\n  } finally {\n    warming.delete(prefixKey)\n  }\n}\n\n/** Forgets every warmed prefix; for specs. */\nexport function resetAiDevWarmPrefixes(): void {\n  warming.clear()\n  warmedAt.clear()\n}\n\n// ── What a live eval prints ──────────────────────────────────────────────\n\n/**\n * The line every live eval's table carries (AGL-3660): how many of its\n * requests went to the provider and how many were answered from disk, what\n * the live ones cost at list, and how many batches carried them. A table\n * whose `live` is 0 proved nothing new — every prompt in it had been answered\n * before — and is not a live pass; `AGLYN_AI_REPLAY=refresh` asks again.\n */\nexport function aiLiveRunLedger(env: Env = process.env): AiDevReplayStats & {\n  batches: number\n  batchedRequests: number\n  allReplayed: boolean\n} {\n  const replay = aiDevReplayStats(env)\n  const batch = aiLiveBatchStats()\n  return {\n    ...replay,\n    batches: batch.batches,\n    batchedRequests: batch.requests,\n    allReplayed: replay.live === 0 && replay.replayed > 0,\n  }\n}\n"],"names":["createHash","existsSync","mkdirSync","readFileSync","renameSync","writeFileSync","dirname","join","estimateAiProviderCostUsd","aiLiveBatchStats","AI_REPLAY_DIR_ENV","aiDevReplayMode","KEY_VERSION","aiCanonicalJson","value","JSON","stringify","sortKeys","Array","isArray","map","Object","fromEntries","keys","sort","filter","key","undefined","aiDevReplayKey","providerId","stream","request","update","v","provider","model","system","block","text","tools","messages","maxTokens","thinking","effort","digest","aiCachedPrefixKey","last","Boolean","cacheBreakpoint","lastIndexOf","slice","repositoryRoot","start","process","cwd","dir","parent","aiDevReplayDir","env","pathFor","readRecording","path","parsed","parse","writeRecording","recording","recursive","temp","pid","stats","mode","live","replayed","liveProviderUsd","savedProviderUsd","aiDevReplayStats","round","resetAiDevReplayStats","usd","Math","usageCost","usage","aiDevCountLive","discount","replayEvents","events","event","recordEvents","source","onDone","completed","push","type","some","aiDevReplayComplete","send","id","recorded","kind","result","recordedAt","Date","toISOString","aiDevReplayStream","done","find","warming","Map","warmedAt","aiDevWarmPrefixFirst","prefixKey","ttlMs","now","warmed","get","pending","catch","first","set","delete","resetAiDevWarmPrefixes","clear","aiLiveRunLedger","replay","batch","batches","batchedRequests","requests","allReplayed"],"mappings":";;;;AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,UAAU,QAAQ,cAAa;AACxC,SAASC,UAAU,EAAEC,SAAS,EAAEC,YAAY,EAAEC,UAAU,EAAEC,aAAa,QAAQ,UAAS;AACxF,SAASC,OAAO,EAAEC,IAAI,QAAQ,YAAW;AACzC,SAASC,yBAAyB,QAAQ,0BAAsB;AAShE,SAASC,gBAAgB,QAAQ,qBAAiB;AAClD,SAASC,iBAAiB,EAAEC,eAAe,QAAoD,kBAAc;AAE7G,mHAAmH,GACnH,MAAMC,cAAc;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkCC,GAED,4EAA4E;AAE5E,sGAAsG,GACtG,OAAO,SAASC,gBAAgBC,KAAc;IAC5C,OAAOC,KAAKC,SAAS,CAACC,SAASH;AACjC;AAEA,SAASG,SAASH,KAAc;IAC9B,IAAII,MAAMC,OAAO,CAACL,QAAQ,OAAOA,MAAMM,GAAG,CAACH;IAC3C,IAAIH,SAAS,OAAOA,UAAU,UAAU;QACtC,OAAOO,OAAOC,WAAW,CACvBD,OAAOE,IAAI,CAACT,OACTU,IAAI,GACJC,MAAM,CAAC,CAACC,MAAQ,AAACZ,KAAiC,CAACY,IAAI,KAAKC,WAC5DP,GAAG,CAAC,CAACM,MAAQ;gBAACA;gBAAKT,SAAS,AAACH,KAAiC,CAACY,IAAI;aAAE;IAE5E;IACA,OAAOZ;AACT;AAaA,+EAA+E,GAC/E,OAAO,SAASc,eAAeC,UAAkB,EAAEC,MAAe,EAAEC,OAAwB;QAU7EA,gBAGGA,mBACFA;IAbd,OAAO/B,WAAW,UACfgC,MAAM,CACLnB,gBAAgB;QACdoB,GAAGrB;QACHsB,UAAUL;QACVC;QACAK,OAAOJ,QAAQI,KAAK;QACpB,mEAAmE;QACnEC,QAAQL,QAAQK,MAAM,CAAChB,GAAG,CAAC,CAACiB,QAAUA,MAAMC,IAAI;QAChDC,KAAK,GAAER,iBAAAA,QAAQQ,KAAK,YAAbR,iBAAiB,EAAE;QAC1BS,UAAUT,QAAQS,QAAQ;QAC1BC,WAAWV,QAAQU,SAAS;QAC5BC,QAAQ,GAAEX,oBAAAA,QAAQW,QAAQ,YAAhBX,oBAAoB;QAC9BY,MAAM,GAAEZ,kBAAAA,QAAQY,MAAM,YAAdZ,kBAAkB;IAC5B,IAEDa,MAAM,CAAC;AACZ;AAEA;;;;CAIC,GACD,OAAO,SAASC,kBAAkBd,OAA4D;QAO/EA;IANb,MAAMe,OAAOf,QAAQK,MAAM,CAAChB,GAAG,CAAC,CAACiB,QAAUU,QAAQV,MAAMW,eAAe,GAAGC,WAAW,CAAC;IACvF,IAAIH,OAAO,GAAG,OAAO;IACrB,OAAO9C,WAAW,UACfgC,MAAM,CACLnB,gBAAgB;QACdsB,OAAOJ,QAAQI,KAAK;QACpBI,KAAK,GAAER,iBAAAA,QAAQQ,KAAK,YAAbR,iBAAiB,EAAE;QAC1BK,QAAQL,QAAQK,MAAM,CAACc,KAAK,CAAC,GAAGJ,OAAO,GAAG1B,GAAG,CAAC,CAACiB,QAAUA,MAAMC,IAAI;IACrE,IAEDM,MAAM,CAAC;AACZ;AAEA,4EAA4E;AAE5E,2GAA2G,GAC3G,SAASO,eAAeC,QAAgBC,QAAQC,GAAG,EAAE;IACnD,IAAIC,MAAMH;IACV,OAAS;QACP,IAAInD,WAAWM,KAAKgD,KAAK,aAAa,OAAOA;QAC7C,MAAMC,SAASlD,QAAQiD;QACvB,IAAIC,WAAWD,KAAK,OAAOH;QAC3BG,MAAMC;IACR;AACF;AAEA,qCAAqC,GACrC,OAAO,SAASC,eAAeC,MAAWL,QAAQK,GAAG;IACnD,OAAOA,GAAG,CAAChD,kBAAkB,IAAIH,KAAK4C,kBAAkB,UAAU;AACpE;AAMA,SAASQ,QAAQJ,GAAW,EAAE7B,GAAW;IACvC,OAAOnB,KAAKgD,KAAK7B,IAAIwB,KAAK,CAAC,GAAG,IAAI,GAAGxB,IAAI,KAAK,CAAC;AACjD;AAEA,SAASkC,cAAcL,GAAW,EAAE7B,GAAW;IAC7C,MAAMmC,OAAOF,QAAQJ,KAAK7B;IAC1B,IAAI,CAACzB,WAAW4D,OAAO,OAAO;IAC9B,IAAI;QACF,MAAMC,SAAS/C,KAAKgD,KAAK,CAAC5D,aAAa0D,MAAM;QAC7C,OAAOC,CAAAA,0BAAAA,OAAQ7B,CAAC,MAAKrB,eAAekD,OAAOpC,GAAG,KAAKA,MAAMoC,SAAS;IACpE,EAAE,eAAM;QACN,OAAO;IACT;AACF;AAEA,SAASE,eAAeT,GAAW,EAAEU,SAAoB;IACvD,MAAMJ,OAAOF,QAAQJ,KAAKU,UAAUvC,GAAG;IACvCxB,UAAUI,QAAQuD,OAAO;QAAEK,WAAW;IAAK;IAC3C,sFAAsF;IACtF,MAAMC,OAAO,GAAGN,KAAK,CAAC,EAAER,QAAQe,GAAG,CAAC,IAAI,CAAC;IACzC/D,cAAc8D,MAAMpD,KAAKC,SAAS,CAACiD;IACnC7D,WAAW+D,MAAMN;AACnB;AAiBA,MAAMQ,QAA0B;IAC9BC,MAAM;IACNC,MAAM;IACNC,UAAU;IACVC,iBAAiB;IACjBC,kBAAkB;AACpB;AAEA,2EAA2E,GAC3E,OAAO,SAASC,iBAAiBjB,MAAWL,QAAQK,GAAG;IACrD,OAAO,aACFW;QACHC,MAAM3D,gBAAgB+C;QACtBe,iBAAiBG,MAAMP,MAAMI,eAAe;QAC5CC,kBAAkBE,MAAMP,MAAMK,gBAAgB;;AAElD;AAEA,sEAAsE,GACtE,OAAO,SAASG;IACdR,MAAME,IAAI,GAAG;IACbF,MAAMG,QAAQ,GAAG;IACjBH,MAAMI,eAAe,GAAG;IACxBJ,MAAMK,gBAAgB,GAAG;AAC3B;AAEA,SAASE,MAAME,GAAW;IACxB,OAAOC,KAAKH,KAAK,CAACE,MAAM,WAAa;AACvC;AAEA,SAASE,UAAUC,KAAwB,EAAE9C,KAAa;IACxD,OAAO3B,0BAA0ByE,OAAO9C;AAC1C;AAEA,2GAA2G,GAC3G,OAAO,SAAS+C,eAAeD,KAAwB,EAAE9C,KAAa,EAAEgD,WAAW,CAAC;IAClFd,MAAME,IAAI,IAAI;IACdF,MAAMI,eAAe,IAAIO,UAAUC,OAAO9C,SAASgD;AACrD;AAEA,4EAA4E;AAE5E,SAAgBC,aAAaC,MAAgC;;QAC3D,KAAK,MAAMC,SAASD,OAAQ,MAAMC;IACpC;;AAEA,8EAA8E,GAC9E,SAAgBC,aACdC,MAAoC,EACpCC,MAAyC;;QAEzC,MAAMJ,SAA0B,EAAE;QAClC,IAAIK,YAAY;QAChB;;YAAA,IAAkC;gBAAlC,oCAA0BF,8IAAQ;;0BAAjBF;oBACfD,OAAOM,IAAI,CAACL;oBACZ,IAAIA,MAAMM,IAAI,KAAK,QAAQF,YAAY;oBACvC,MAAMJ;gBACR;YAAA;;;;;;;;;;;;;;QAAA;QACA,sEAAsE;QACtE,iDAAiD;QACjD,IAAII,aAAa,CAACL,OAAOQ,IAAI,CAAC,CAACP,QAAUA,MAAMM,IAAI,KAAK,UAAUH,OAAOJ;IAC3E;;AAEA;;;;CAIC,GACD,OAAO,eAAeS,oBACpB5D,QAAgC,EAChCH,OAAwB,EACxBuC,IAAqC,EACrCyB,IAA6B,EAC7BrC,MAAWL,QAAQK,GAAG;IAEtB,MAAMH,MAAME,eAAeC;IAC3B,MAAMhC,MAAME,eAAeM,SAAS8D,EAAE,EAAE,OAAOjE;IAC/C,MAAMkE,WAAW3B,SAAS,WAAWV,cAAcL,KAAK7B,OAAO;IAC/D,IAAIuE,CAAAA,4BAAAA,SAAUC,IAAI,MAAK,UAAU;QAC/B7B,MAAMG,QAAQ,IAAI;QAClBH,MAAMK,gBAAgB,IAAIM,UAAUiB,SAASE,MAAM,CAAClB,KAAK,EAAElD,QAAQI,KAAK;QACxE,OAAO8D,SAASE,MAAM;IACxB;IACA,MAAMA,SAAS,MAAMJ;IACrB/B,eAAeT,KAAK;QAClBtB,GAAGrB;QACHc;QACAS,OAAOJ,QAAQI,KAAK;QACpBiE,YAAY,IAAIC,OAAOC,WAAW;QAClCJ,MAAM;QACNC;IACF;IACA,OAAOA;AACT;AAEA,uDAAuD,GACvD,OAAO,eAAeI,kBACpBrE,QAAgC,EAChCH,OAAwB,EACxBuC,IAAqC,EACrCyB,IAAiD,EACjDrC,MAAWL,QAAQK,GAAG;IAEtB,MAAMH,MAAME,eAAeC;IAC3B,MAAMhC,MAAME,eAAeM,SAAS8D,EAAE,EAAE,MAAMjE;IAC9C,MAAMkE,WAAW3B,SAAS,WAAWV,cAAcL,KAAK7B,OAAO;IAC/D,IAAIuE,CAAAA,4BAAAA,SAAUC,IAAI,MAAK,UAAU;QAC/B7B,MAAMG,QAAQ,IAAI;QAClB,MAAMgC,OAAOP,SAASZ,MAAM,CAACoB,IAAI,CAAC,CAACnB,QAAUA,MAAMM,IAAI,KAAK;QAC5D,IAAIY,CAAAA,wBAAAA,KAAMZ,IAAI,MAAK,QAAQvB,MAAMK,gBAAgB,IAAIM,UAAUwB,KAAKvB,KAAK,EAAElD,QAAQI,KAAK;QACxF,OAAOiD,aAAaa,SAASZ,MAAM;IACrC;IACA,MAAMd,OAAO,MAAMwB;IACnB,OAAOR,aAAahB,MAAM,CAACc;QACzB,MAAMmB,OAAOnB,OAAOoB,IAAI,CAAC,CAACnB,QAAUA,MAAMM,IAAI,KAAK;QACnD,IAAIY,CAAAA,wBAAAA,KAAMZ,IAAI,MAAK,QAAQV,eAAesB,KAAKvB,KAAK,EAAElD,QAAQI,KAAK;QACnE6B,eAAeT,KAAK;YAClBtB,GAAGrB;YACHc;YACAS,OAAOJ,QAAQI,KAAK;YACpBiE,YAAY,IAAIC,OAAOC,WAAW;YAClCJ,MAAM;YACNb;QACF;IACF;AACF;AAEA,4EAA4E;AAE5E;;;;;;;;;;;CAWC,GACD,MAAMqB,UAAU,IAAIC;AACpB,MAAMC,WAAW,IAAID;AAErB,OAAO,eAAeE,qBACpBC,SAAwB,EACxBC,KAAa,EACbhB,IAAsB,EACtBiB,MAAoBX,KAAKW,GAAG;IAE5B,IAAI,CAACF,WAAW,OAAOf;IACvB,MAAMkB,SAASL,SAASM,GAAG,CAACJ;IAC5B,IAAIG,WAAWtF,aAAaqF,QAAQC,SAASF,OAAO,OAAOhB;IAC3D,MAAMoB,UAAUT,QAAQQ,GAAG,CAACJ;IAC5B,IAAIK,SAAS;QACX,MAAMA,QAAQC,KAAK,CAAC,IAAMzF;QAC1B,OAAOoE;IACT;IACA,MAAMsB,QAAQtB;IACdW,QAAQY,GAAG,CAACR,WAAWO;IACvB,IAAI;QACF,MAAMlB,SAAS,MAAMkB;QACrBT,SAASU,GAAG,CAACR,WAAWE;QACxB,OAAOb;IACT,SAAU;QACRO,QAAQa,MAAM,CAACT;IACjB;AACF;AAEA,4CAA4C,GAC5C,OAAO,SAASU;IACdd,QAAQe,KAAK;IACbb,SAASa,KAAK;AAChB;AAEA,4EAA4E;AAE5E;;;;;;CAMC,GACD,OAAO,SAASC,gBAAgBhE,MAAWL,QAAQK,GAAG;IAKpD,MAAMiE,SAAShD,iBAAiBjB;IAChC,MAAMkE,QAAQnH;IACd,OAAO,aACFkH;QACHE,SAASD,MAAMC,OAAO;QACtBC,iBAAiBF,MAAMG,QAAQ;QAC/BC,aAAaL,OAAOpD,IAAI,KAAK,KAAKoD,OAAOnD,QAAQ,GAAG;;AAExD"}

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

@@ -382,6 +382,53 @@ export declare function detectAdHocWidths(tree: AiDoctrineTree, outputKind: AiOu
  * absent, and only what was written can name them.
  */
 export declare function detectUnresponsiveGrids(tree: AiDoctrineTree, outputKind: AiOutputKind, written?: (id: string) => unknown): AiDoctrineViolation[];
+/**
+ * Rule 12's `grid-item-size`, settled before the check reads it where it has
+ * one answer (AGL-3596), as `aiSettlePlanRefs` settles a plan. The re-ask for
+ * it states the very size to write, and a production Home page was refused and
+ * refunded after its re-ask still left a container's items unsized: the model
+ * breaks a different rule each run, and a rule whose answer the validator
+ * already knows is applied rather than asked for.
+ *
+ * For every Grid container, its items are read exactly as
+ * `detectUnresponsiveGrids` counts them, a Box or a Stack holding nothing but
+ * sized Grid items lending its items to the container:
+ *
+ * - an item whose size is missing, or is not full width on a phone, takes the
+ *   size the model wrote as an object of breakpoints where that one is full
+ *   width on a phone, and otherwise the size the re-ask would ask for
+ *   (`gridItemSizeFor`);
+ * - an element that is no Grid, directly in the container, is wrapped in a new
+ *   Grid item of that size, minted the way the palette validator mints ids;
+ * - a container of several items none of which steps down to columns at a
+ *   larger width takes that size on every item, which is what the re-ask asks;
+ * - a `container` written as the text "true" in any case or spacing
+ *   (`grid-container-text`) is true, since it can mean nothing else.
+ *
+ * A size that is already full width on a phone is kept. Nothing else rule 12
+ * names is touched: a Grid that is not a container may be meant as a row or as
+ * a stack (`grid-not-container`, `grid-as-stack`), and a sized item inside a
+ * Box (`grid-item-outside-container`) is moved only by changing the Box.
+ *
+ * `written` is the node as the model wrote it, by an id of `tree`, as
+ * `detectUnresponsiveGrids` reads it, for a tree the palette validator has
+ * read; a tree as the model wrote it is read as it stands, which is how the
+ * tree check settles a layout, a template or a component (`aiSettleWrittenGridItems`).
+ * A tree with nothing to settle comes back
+ * as the same object, so settling is idempotent. A node that is changed is
+ * copied, never edited in place.
+ */
+export declare function aiSettleGridItems<T extends AiDoctrineTree>(tree: T, options?: {
+    written?: (id: string) => unknown;
+    mintId?: () => string;
+}): T;
+/**
+ * `aiSettleGridItems` on a tree as the model wrote it, before the palette
+ * validator reads it (AGL-3596): the tree check every kind but a page section
+ * goes through stores what the validator makes of its answer, so the answer
+ * is settled first. Anything that is no flat node map comes back as it was.
+ */
+export declare function aiSettleWrittenGridItems(input: unknown): unknown;
 /** Whether an element is one rule 10 holds to a destination: a Button or a Screen Link. */
 export declare function isAiLinkElement(componentId: unknown): boolean;
 /**
@@ -576,6 +623,41 @@ export declare function estimateAiOutputLoad(score: AiOutputScore, outputKind: A
  * validator drops anything, so a re-ask can quote the node at fault.
  */
 export declare function detectDisagreeingNodes(input: unknown): AiDoctrineViolation[];
+/**
+ * A node map that does not agree with itself, settled where it has one
+ * reading (AGL-3596), before `detectDisagreeingNodes` reads it. A guided
+ * start's Home page stopped on each of these after its re-ask, and each is
+ * one line the model left out, not a choice it made.
+ *
+ * - A name listed under `nodes` that the map never holds is taken out of the
+ *   list: there is nothing written to place there.
+ * - An element written and listed by nobody goes where the model said it
+ *   goes, when its own `parentId` names an element the tree reaches that can
+ *   hold it. Failing that, a single such element goes in the single element
+ *   the tree reaches that can hold elements and holds none, which is the shape
+ *   of a row whose item was written beside it. Failing both, it is dropped,
+ *   with everything under it: nothing on the page holds it, and none of it
+ *   would ever be shown.
+ * - A repeated item (`repeat`) is the exception: dropping it would lose every
+ *   card it draws, so one that cannot be placed is left for the re-ask.
+ *
+ * Reads and returns the tree as the model wrote it; an input with nothing to
+ * settle comes back as the same object.
+ */
+export declare function aiSettleDisagreeingNodes(input: unknown): unknown;
+/**
+ * A heading written past the headline ceiling, settled where it has one
+ * reading (AGL-3596). The palette validator cuts such a line where the
+ * ceiling falls, mid-word, and the check refuses the cut (rule 14,
+ * `copy-cut-at-ceiling`); live guided starts' heroes stopped on it after
+ * their re-ask. A heading whose first sentence or clause ends within the
+ * ceiling is a whole line already, so it is kept to that, its later words
+ * dropped: "Free inspections after a storm, with photos of every shingle we
+ * replace and a written…" becomes "Free inspections after a storm". A heading
+ * with no such boundary, or whose part within is a stub, is left for the
+ * re-ask. Reads and returns the tree as the model wrote it.
+ */
+export declare function aiSettleCutHeadings(input: unknown): unknown;
 export interface AiDoctrineTreeReport {
     ok: boolean;
     /** The palette validator's result: the tree to store, its repairs and its id map. */