onto-mcp 0.4.12 → 0.4.13

package/dist/core-runtime/review/review-prompt-budget.js

@@ -0,0 +1,97 @@
+import { REVIEW_EXECUTION_UNIT_IDS } from "../discovery/settings-chain.js";
+import { reviewExecutionUnitActor } from "./review-execution-profile.js";
+/**
+ * Reference context window (tokens) that maps to multiplier 1 — the smallest
+ * window that still earns the DEFAULT (unchanged) budget. A window at or below
+ * this floors to multiplier 1. PRELIMINARY (INV-BENCH-1).
+ */
+export const BASELINE_WINDOW_TOKENS = 200_000;
+/**
+ * The fixed embed line budget applied to a packet embed when no window-scaled
+ * value is resolved — the no-regression floor and the single source of this
+ * value, shared by the prepare-time budget resolution and the packet stage's
+ * fallback. (Unchanged from the historical packet-stage default of 300.)
+ */
+export const DEFAULT_MAX_EMBED_LINES = 300;
+/**
+ * Hard ceiling on the window multiplier, so an arbitrarily large window cannot
+ * blow up the prompt budget without bound. PRELIMINARY (INV-BENCH-1).
+ */
+export const MAX_WINDOW_MULTIPLIER = 4;
+/**
+ * Convert a resolved context window (tokens) into a budget multiplier.
+ * undefined (unresolved model / no registered window) → 1 (no regression).
+ * Otherwise clamp(window / BASELINE_WINDOW_TOKENS, 1, MAX_WINDOW_MULTIPLIER) —
+ * floored at 1 so a small-window model is never penalised below DEFAULT, and
+ * ceilinged at MAX so a huge window cannot grow the budget without bound.
+ */
+export function reviewWindowMultiplier(contextWindowTokens) {
+    if (contextWindowTokens === undefined)
+        return 1;
+    return Math.min(Math.max(contextWindowTokens / BASELINE_WINDOW_TOKENS, 1), MAX_WINDOW_MULTIPLIER);
+}
+/**
+ * Window-proportional embed line budget — the true binding cut applied to the
+ * packet embed (`truncateForEmbedding`). Floored at `defaultMaxEmbedLines` so
+ * multiplier 1 returns the unchanged DEFAULT (no regression), and ceilinged at
+ * `defaultMaxEmbedLines * MAX_WINDOW_MULTIPLIER`.
+ */
+export function deriveReviewMaxEmbedLines(multiplier, defaultMaxEmbedLines) {
+    return Math.min(Math.max(Math.round(defaultMaxEmbedLines * multiplier), defaultMaxEmbedLines), defaultMaxEmbedLines * MAX_WINDOW_MULTIPLIER);
+}
+/** Merge an actor llm ref with an optional unit override (override wins per
+ * field), the same shallow merge the execution-profile resolver uses. Returns
+ * undefined only when both are absent. */
+function mergeLensLlmRef(base, override) {
+    if (!base && !override)
+        return undefined;
+    return { ...(base ?? {}), ...(override ?? {}) };
+}
+/** Look up the registered context window (tokens) for a resolved lens llm ref.
+ * The registry key is the MODEL provider + model id (e.g. openai/gpt-5.5), NOT
+ * the runtime execution adapter (codex_cli / claude_code). An unresolved
+ * provider or model, an unregistered pair, or an entry without a window all
+ * yield undefined. */
+function resolveLlmRefWindowTokens(llm, registry) {
+    const provider = llm?.provider;
+    const modelId = llm?.model;
+    if (!provider || !modelId)
+        return undefined;
+    return registry.supported_models.find((entry) => entry.provider === provider && entry.model === modelId)?.context_window_tokens;
+}
+/**
+ * Resolve the lens model's context window (tokens) for the review prompt budget.
+ *
+ * All lenses share the single "lens" actor model, so the common path resolves
+ * that one representative (`execution.lens.llm`). When a lens-CLASS unit override
+ * (a unit whose actor is "lens": lens / issue_stance_response /
+ * deliberation_response) selects a different model, every such effective lens
+ * model is resolved and the MINIMUM window is taken — the min can never overflow
+ * any lens, so the budget stays safe for the smallest-window lens (the floor
+ * keeps it conservative).
+ *
+ * Returns undefined when no lens model resolves to a registered window, so the
+ * caller falls through to multiplier 1 → DEFAULT budgets (no regression). Never
+ * throws.
+ */
+export function resolveReviewLensContextWindowTokens(execution, registry) {
+    const lensActorLlm = execution.lens.llm;
+    const windows = [];
+    const baseWindow = resolveLlmRefWindowTokens(lensActorLlm, registry);
+    if (baseWindow !== undefined)
+        windows.push(baseWindow);
+    for (const unitId of REVIEW_EXECUTION_UNIT_IDS) {
+        if (reviewExecutionUnitActor(unitId) !== "lens")
+            continue;
+        const override = execution.units[unitId]?.llm;
+        if (!override)
+            continue;
+        const effective = mergeLensLlmRef(lensActorLlm, override);
+        const window = resolveLlmRefWindowTokens(effective, registry);
+        if (window !== undefined)
+            windows.push(window);
+    }
+    if (windows.length === 0)
+        return undefined;
+    return Math.min(...windows);
+}

package/dist/core-runtime/review/semantic-quality-gate.js

@@ -1,3 +1,22 @@
+/** The complete check-id universe this gate can emit — the value-level single
+ * source (the check_id type derives from it). The review-cert/v2 evidence
+ * contract pins its per-run check universe against THIS list, so a harness
+ * that omits issue artifacts (the gate then emits a subset — see
+ * runSemanticQualityGate) cannot silently shrink the certified comparison. */
+export const SEMANTIC_QUALITY_GATE_CHECK_IDS = [
+    "material_issue_recall",
+    "final_result_material_issue_recall",
+    "false_materiality_guard",
+    "boundary_uncertainty_preservation",
+    "non_material_finding_preservation",
+    "artifact_material_issue_recall",
+    "causal_materiality_shape",
+    "causal_relation_correctness",
+    "issue_dependency_preservation",
+    "actionability",
+    "count_list_consistency",
+    "grounding",
+];
 const DEFAULT_FIXTURE_ID = "review-pipeline-target-v1";
 const FIXTURES = {
     "review-pipeline-target-v1": {
@@ -458,14 +477,21 @@ export function evaluateReviewPipelineSemanticQualityGate(args) {
         `non_material_finding_count=${nonMaterialFindings.length}`,
         `boundary_notes_chars=${boundaryNotes?.length ?? 0}`,
     ]);
+    // Boundary uncertainty's preservation AUTHORITY is the finding-ledger
+    // (non-material findings), not the final Boundary Notes projection. A model
+    // preserves the decoy's uncertainty by recording it as a non-material,
+    // boundary-contextualized finding; whether it also echoes that into the final
+    // summary is a projection-style choice, not a quality signal — one model may
+    // prioritize the MATERIAL issue's own confidence boundaries in the final note
+    // and keep the non-material decoy in the ledger for audit, which is at least as
+    // sound. So this reads nonMaterialText (the authority) and stays independent of
+    // false_materiality_guard, which checks the ORTHOGONAL axis: the decoy was not
+    // mis-promoted to a material issue. (A decoy surfaced only in the final note but
+    // absent from the authority still fails here — authority is where it must live.)
     const boundaryUncertainty = check("boundary_uncertainty_preservation", !falseMaterialityCandidateObserved ||
-        (boundaryNotes !== null &&
-            textContainsAny(boundaryNotesText, fixture.boundaryUncertaintyTerms) &&
-            textContainsAny(boundaryNotesText, fixture.boundaryContextTerms)), [
-        boundaryNotes === null
-            ? "Boundary Notes section missing"
-            : `Boundary Notes chars=${boundaryNotes.length}`,
-        `expected: compact note preserving ${fixture.boundaryUncertaintyTerms.join(", ")} uncertainty`,
+        containsBoundarySensitiveUncertainty(nonMaterialText, fixture), [
+        `non_material_boundary_chars=${nonMaterialText.length}`,
+        `expected boundary uncertainty (${fixture.boundaryUncertaintyTerms.join(", ")}) preserved in the finding-ledger authority (non-material findings)`,
     ]);
     const materialActionRefs = new Set(materialIssues.flatMap((issue) => strings(issue.action_candidates)));
     for (const item of actionCandidates) {

package/dist/core-runtime/review/spreadsheet-review-disposition.js

@@ -0,0 +1,94 @@
+import path from "node:path";
+import { inventoryHasRenderableStructure, } from "../spreadsheet-structure-observer.js";
+/**
+ * risk_signal kinds that do NOT count as `structural_risk_signals` backing:
+ *  - `unreadable_sheet_part`: an observation-failure marker, not a structural risk (so a
+ *    risk-only corrupt shell backs nothing → not inspectable; R4 held).
+ *  - `macro_present`: already owned by `access_and_protection_hygiene` (the observer pushes
+ *    BOTH a `macro_present` boolean and a `macro_present` risk_signal — counting the signal
+ *    here would double-back and re-open the #3/R4 asymmetry).
+ *  - `external_links_present`: already owned by the explicit `external_links.length > 0`
+ *    clause (same double-back hazard).
+ * The genuine residual structural-risk kinds are `ragged_row`, `oversized_zip_entry`,
+ * `pivot_table_cap`. (Error cells are NOT risk_signals — they live in `error_cells[]`,
+ * ORed in separately below.)
+ */
+const NON_STRUCTURAL_RISK_KINDS = new Set([
+    "unreadable_sheet_part",
+    "macro_present",
+    "external_links_present",
+]);
+/** True when a risk_signal kind is a genuine structural risk (not an observation-failure
+ *  marker or a signal already owned by another obligation). */
+export function isStructuralRiskSignal(kind) {
+    return !NON_STRUCTURAL_RISK_KINDS.has(kind);
+}
+/**
+ * The positive backing rule: each spreadsheet review obligation is listed only when its
+ * specific evidence exists in this ref's inventory. Mirrors the catalog in
+ * `reviewMaterialGoals("spreadsheet")` (target-material-kind.ts) one-to-one.
+ */
+function computeBackedGoals(inv) {
+    const goals = [];
+    if (inv.formula_cells_total > 0) {
+        goals.push("formula_integrity");
+    }
+    if (inv.formula_patterns.some((pattern) => pattern.cross_sheet_refs.length > 0) ||
+        inv.cross_sheet_key_overlap.length > 0) {
+        goals.push("cross_sheet_reference_integrity");
+    }
+    if (inv.named_ranges.length > 0) {
+        goals.push("named_range_hygiene");
+    }
+    if (inv.data_validations.length > 0) {
+        goals.push("data_validation_coverage");
+    }
+    if (inv.macro_present || inv.sheets.some((sheet) => sheet.hidden || sheet.protected)) {
+        goals.push("access_and_protection_hygiene");
+    }
+    if (inv.risk_signals.some((signal) => isStructuralRiskSignal(signal.kind)) ||
+        inv.external_links.length > 0 ||
+        inv.error_cells.length > 0) {
+        goals.push("structural_risk_signals");
+    }
+    return goals;
+}
+/**
+ * Compute the single per-ref disposition from the shared workbook inventory (or its
+ * absence). Pure, total: never throws. `inventory` is undefined when the ref was never
+ * observed (e.g. a directory path that did not pass isSpreadsheetRef).
+ */
+export function computeSpreadsheetDisposition(inventory, ref) {
+    const resolved = path.resolve(ref);
+    if (inventory === undefined) {
+        return {
+            ref: resolved,
+            inspectable: false,
+            reason: `${resolved}: workbook not observed`,
+            sha256: null,
+            backed_goals: [],
+        };
+    }
+    // The observer declined/failed to read it (unsupported format, unreadable, oversized,
+    // or a guarded decode crash) — content_sha256 is "" on a true skip, the real hash when
+    // the bytes were read but extraction is unimplemented (.xls etc.).
+    if (inventory.unsupported_reason !== null) {
+        return {
+            ref: resolved,
+            inspectable: false,
+            reason: `${resolved}: ${inventory.unsupported_reason}`,
+            sha256: inventory.content_sha256 || null,
+            backed_goals: [],
+        };
+    }
+    const renderable = inventoryHasRenderableStructure(inventory);
+    return {
+        ref: resolved,
+        inspectable: renderable,
+        reason: renderable
+            ? null
+            : `${resolved}: no renderable structure (empty or unreadable workbook)`,
+        sha256: inventory.content_sha256 || null,
+        backed_goals: renderable ? computeBackedGoals(inventory) : [],
+    };
+}

package/dist/core-runtime/route-identity.js

@@ -0,0 +1,182 @@
+/**
+ * Unified route identity (effort-calibration simplification, design
+ * 20260617-effort-calibration-simplification-telemetry-derived-design.md §5).
+ *
+ * A RouteIdentity is a projection of the model-switcher's already-resolved
+ * selection — it REUSES LlmExecutionAdapter / LlmProviderName / LlmBillingMode
+ * rather than minting a parallel vocabulary. The only genuinely new fields are
+ * `route_provenance` (witnessed vs profile-derived) and `route_completeness`
+ * (whether the route resolved past model_provider).
+ *
+ * Provenance honesty (design §3, §8):
+ *  - reconstruct derives execution_adapter / model_provider from the resolved
+ *    selection carried on the call config (witnessed at the call boundary), NOT
+ *    by reverse-mapping effective_base_url (which cannot recover model_provider
+ *    for codex-cli://oauth or a custom openai-compatible base).
+ *  - billing_mode is a code-path constant (`declared_billing_mode`), so it stays
+ *    declared-provenance even on the reconstruct (otherwise witnessed) side.
+ *  - effective_base_url is corroboration only, and identifies custom proxy bases
+ *    that downgrade route_completeness.
+ */
+import { DEFAULT_GROK_BASE_URL, DEFAULT_LMSTUDIO_BASE_URL, } from "./llm/model-switcher.js";
+/**
+ * Map the model-switcher's RuntimeLlmProvider brand to the canonical model
+ * vendor. The only brand that differs from its model_provider is `codex` (the
+ * openai OAuth brand). Returns null for an unknown brand (route_completeness
+ * then degrades to under_determined).
+ */
+export function modelProviderFromRuntimeProvider(provider) {
+    switch (provider) {
+        case "codex":
+        case "openai":
+            return "openai";
+        case "anthropic":
+            return "anthropic";
+        case "grok":
+            return "grok";
+        case "lmstudio":
+            return "lmstudio";
+        default:
+            return null;
+    }
+}
+/** The non-default openai-compatible bases that ARE normal provider routes. */
+const KNOWN_OPENAI_COMPATIBLE_BASE_URLS = new Set([
+    DEFAULT_GROK_BASE_URL,
+    DEFAULT_LMSTUDIO_BASE_URL,
+]);
+/**
+ * Whether an `openai_compatible_http` route runs against a CUSTOM proxy base —
+ * a base_url that is neither a mock sentinel nor one of the known provider
+ * defaults. The selection still resolves an adapter + model_provider, but a
+ * custom endpoint cannot be treated as the normal provider route (design §6 MF2):
+ * effective_base_url is corroboration only, so a custom base downgrades
+ * route_completeness rather than passing as fully witnessed.
+ */
+function isCustomOpenAiCompatibleBase(adapter, baseUrl) {
+    if (adapter !== "openai_compatible_http")
+        return false;
+    if (!baseUrl)
+        return false;
+    return !KNOWN_OPENAI_COMPATIBLE_BASE_URLS.has(baseUrl);
+}
+function completeness(adapter, modelProvider, baseUrl) {
+    if (!modelProvider)
+        return "under_determined";
+    if (!adapter)
+        return "provider_only";
+    if (isCustomOpenAiCompatibleBase(adapter, baseUrl))
+        return "provider_only";
+    return "complete";
+}
+/**
+ * Build the witnessed reconstruct RouteIdentity from the fields available at the
+ * call-record boundary: the resolved provider brand and execution_adapter
+ * carried on the call config (witnessed), the call result's declared billing
+ * mode and effective_base_url. A `mock://` base short-circuits to the mock
+ * adapter (coarse; reconstruct contributes no realization).
+ */
+export function witnessedReconstructRouteIdentity(input) {
+    const effectiveBaseUrl = input.effectiveBaseUrl ?? null;
+    if (effectiveBaseUrl?.startsWith("mock://")) {
+        return {
+            execution_adapter: "mock",
+            model_provider: null,
+            billing_mode: input.declaredBillingMode ?? "local",
+            effective_base_url: effectiveBaseUrl,
+            route_provenance: "witnessed",
+            route_completeness: "complete",
+            realization: null,
+        };
+    }
+    const adapter = input.executionAdapter ?? null;
+    const modelProvider = modelProviderFromRuntimeProvider(input.provider);
+    return {
+        execution_adapter: adapter,
+        model_provider: modelProvider,
+        billing_mode: input.declaredBillingMode ?? null,
+        effective_base_url: effectiveBaseUrl,
+        route_provenance: "witnessed",
+        route_completeness: completeness(adapter, modelProvider, effectiveBaseUrl),
+        realization: null,
+    };
+}
+/**
+ * Build a profile-derived RouteIdentity from a review route projection (already
+ * structurally rich: adapter / model_provider / billing / base_url). Review has
+ * no result-level base_url witness, so provenance is profile_derived (design
+ * §4, §11.1). `realization` (semantic_mock | boundary_stub | fixture) is
+ * review-only.
+ */
+export function profileDerivedRouteIdentity(input) {
+    const adapter = input.executionAdapter ?? null;
+    const modelProvider = input.modelProvider ?? null;
+    const effectiveBaseUrl = input.effectiveBaseUrl ?? null;
+    return {
+        execution_adapter: adapter,
+        model_provider: modelProvider,
+        billing_mode: input.billingMode ?? null,
+        effective_base_url: effectiveBaseUrl,
+        route_provenance: "profile_derived",
+        route_completeness: completeness(adapter, modelProvider, effectiveBaseUrl),
+        realization: input.realization ?? null,
+    };
+}
+/**
+ * Derived single-string projection of a RouteIdentity for CLI `--route`
+ * comparison and grouping keys. The structured RouteIdentity stays canonical;
+ * this is a lossy projection (design §11.2). Shape:
+ * `<adapter|provider_only>:<billing>:<model_provider>`.
+ */
+export function routeToken(identity) {
+    const adapter = identity.execution_adapter ?? "provider_only";
+    const billing = identity.billing_mode ?? "unknown";
+    const provider = identity.model_provider ?? "unknown";
+    return `${adapter}:${billing}:${provider}`;
+}
+const ROUTE_COMPLETENESS_ORDER = {
+    complete: 0,
+    provider_only: 1,
+    under_determined: 2,
+};
+/**
+ * The most degraded completeness across a set of identities. The route axis of
+ * the decision-grade gate (design §7 Q3) uses the worst — one legacy
+ * provider-only source taints the merged profile's route. `complete` is the
+ * fold identity (an empty list returns `complete`); a caller that treats "no
+ * identities at all" as a degradation must handle the empty case itself.
+ */
+export function worstRouteCompleteness(values) {
+    let worst = "complete";
+    for (const value of values) {
+        if (ROUTE_COMPLETENESS_ORDER[value] > ROUTE_COMPLETENESS_ORDER[worst]) {
+            worst = value;
+        }
+    }
+    return worst;
+}
+/**
+ * Whether a declared `--route` hint corroborates a derived identity. The hint is
+ * a human label — historically provider-level (`"anthropic"`) or the slash form
+ * (`"anthropic/claude-cli"`) — while the canonical route is the structured
+ * RouteIdentity. The hint is demoted to a non-fatal cross-check (design §5,
+ * §11.2): an EXACT match against the full routeToken, the model_provider, or the
+ * execution_adapter always corroborates. The lenient provider-head fallback
+ * (first slash segment → model_provider) applies ONLY when the adapter is
+ * unknown (provider_only / under_determined): for a `complete` identity the
+ * adapter IS known, so a slash hint naming a different adapter (e.g.
+ * `anthropic/claude-cli` against an `anthropic_sdk` identity) must NOT be
+ * silently corroborated — that would hide the SDK-vs-OAuth split this refactor
+ * exists to surface.
+ */
+export function routeHintMatches(hint, identity) {
+    if (hint === routeToken(identity) ||
+        hint === identity.model_provider ||
+        hint === identity.execution_adapter) {
+        return true;
+    }
+    if (identity.route_completeness === "complete")
+        return false;
+    const head = hint.split("/")[0] ?? hint;
+    return head === identity.model_provider;
+}

package/dist/core-runtime/spreadsheet-header-escalation.js

@@ -0,0 +1,204 @@
+/**
+ * P0.5 header escalation (design §10 C′ / §11 ESC-1) — a SEPARATE named step that
+ * runs AFTER the deterministic observer, never inside it. The observer flags a
+ * sheet whose header is ambiguous (e.g. a headerless all-text sheet whose first
+ * DATA row scored as labels) with `header_confidence: "low"`. For those sheets
+ * this step asks an LLM to resolve the header row under a strict bounded-submit
+ * contract, with a deterministic replay cache and a fail-soft downgrade to the
+ * heuristic when the model is unavailable or answers out of contract.
+ *
+ * LLM authority is narrow (capability-boundary): the model returns ONLY a
+ * header-row index (or null); code owns the trigger gate, the submission
+ * validation, the cache key, the downgrade policy, and the recorded provenance.
+ * The model is injected so this module stays deterministic under test; production
+ * wiring adapts the in-process llm caller to {@link HeaderEscalationLlm}. This
+ * module is intentionally unwired — consumers (reconstruct seed-stage / review)
+ * call it as a post-observation step.
+ */
+import crypto from "node:crypto";
+import { SPREADSHEET_OBSERVER_ADAPTER_VERSION } from "./spreadsheet-structure-observer.js";
+/** Bumped when the escalation prompt/contract changes — folds into the cache key
+ *  so a contract change invalidates prior decisions (design §11 CACHE-1). */
+export const HEADER_ESCALATION_TRIGGER_VERSION = 1;
+/** Rows shown to the model — the leading window the observer also scans. */
+export const ESCALATION_ROW_WINDOW = 15;
+/** Columns shown to the model — bounds the prompt for very wide sheets. */
+export const ESCALATION_COL_WINDOW = 40;
+/** Per-cell char cap in the rendered prompt, to keep the payload bounded. */
+const ESCALATION_CELL_CHAR_CAP = 40;
+/** Races the injected model call against an abort budget so a never-settling
+ *  adapter rejects (→ `llm_unavailable`) instead of hanging the await. The timer
+ *  is cleared when the model settles first; a late settle after timeout is
+ *  ignored (no unhandled rejection). */
+function callLlmWithTimeout(llm, args, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            reject(new Error("header_escalation_timeout"));
+        }, timeoutMs);
+        // Defer through a microtask so a synchronous throw from the adapter routes
+        // to the rejection handler (clearing the timer) rather than escaping the
+        // executor with the timer still pending.
+        Promise.resolve()
+            .then(() => llm(args))
+            .then((value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            reject(error instanceof Error ? error : new Error(String(error)));
+        });
+    });
+}
+function renderRowsTable(rows, colCount) {
+    const cols = Math.min(colCount, ESCALATION_COL_WINDOW);
+    const colSuffix = colCount > cols ? ` | … (+${colCount - cols} cols)` : "";
+    return rows
+        .slice(0, ESCALATION_ROW_WINDOW)
+        .map((row, index) => {
+        const cells = Array.from({ length: cols }, (_, col) => (row[col] ?? "")
+            .replace(/\s+/g, " ")
+            .trim()
+            .slice(0, ESCALATION_CELL_CHAR_CAP));
+        return `row ${index}: ${cells.map((cell) => cell || "∅").join(" | ")}${colSuffix}`;
+    })
+        .join("\n");
+}
+/** Bounded prompt: the leading rows + the exact JSON contract. Deterministic in
+ *  the candidate, so its hash anchors the replay cache. */
+export function renderHeaderPrompt(candidate) {
+    const shown = Math.min(candidate.rows.length, ESCALATION_ROW_WINDOW);
+    return [
+        `Sheet "${candidate.sheetName}" has an ambiguous header. Its first ${shown} rows (0-indexed) are below.`,
+        `Identify the single row that is the column HEADER (labels, not data). If the sheet has no header row, answer null.`,
+        ``,
+        renderRowsTable(candidate.rows, candidate.colCount),
+        ``,
+        `Reply with ONLY this JSON and no other fields: {"header_row_index": <0-based row index, or null>}.`,
+    ].join("\n");
+}
+function shortHash(value) {
+    return crypto.createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+/** Deterministic replay key (design §11 CACHE-1): any drift in content,
+ *  extractor/trigger version, prompt, route provider, model id/effort, or
+ *  data-layer caps yields a fresh key, invalidating a stale decision. */
+export function headerEscalationCacheKey(parts) {
+    return crypto
+        .createHash("sha256")
+        .update(JSON.stringify([
+        parts.contentSha256,
+        parts.extractorVersion,
+        parts.triggerVersion,
+        parts.promptHash,
+        parts.provider,
+        parts.modelId,
+        parts.effort,
+        parts.dataLayerCapsHash,
+        parts.sheetName,
+    ]))
+        .digest("hex");
+}
+/** Strict bounded-submit validation: accept ONLY `{ header_row_index }` with an
+ *  in-range integer or null; reject extra/unknown fields, wrong types, and
+ *  out-of-range indices (the model owns no other field). */
+export function parseHeaderSubmission(raw, rowCount) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return null;
+    const keys = Object.keys(raw);
+    if (keys.length !== 1 || keys[0] !== "header_row_index")
+        return null;
+    const value = raw.header_row_index;
+    if (value === null)
+        return { header_row_index: null };
+    if (typeof value !== "number" || !Number.isInteger(value))
+        return null;
+    if (value < 0 || value >= rowCount)
+        return null;
+    return { header_row_index: value };
+}
+/**
+ * Resolve a sheet's header row, escalating to the model only when the heuristic
+ * was ambiguous. A high-confidence heuristic is trusted as-is. Returns the
+ * heuristic (with a `downgradeReason`) whenever the model is unavailable or
+ * answers out of contract, so escalation never blocks observation. Only
+ * successful LLM resolutions are cached (a transient downgrade re-attempts next
+ * run).
+ */
+export async function escalateHeader(candidate, options) {
+    const heuristic = {
+        sheetName: candidate.sheetName,
+        headerRowIndex: candidate.heuristic.headerRowIndex,
+        confidence: candidate.heuristic.confidence,
+        source: "heuristic",
+    };
+    if (candidate.heuristic.confidence === "high")
+        return heuristic;
+    const prompt = renderHeaderPrompt(candidate);
+    const promptHash = shortHash(prompt);
+    const cacheKey = headerEscalationCacheKey({
+        contentSha256: options.contentSha256,
+        extractorVersion: SPREADSHEET_OBSERVER_ADAPTER_VERSION,
+        triggerVersion: HEADER_ESCALATION_TRIGGER_VERSION,
+        promptHash,
+        provider: options.model.provider,
+        modelId: options.model.id,
+        effort: options.model.effort,
+        dataLayerCapsHash: options.dataLayerCapsHash,
+        sheetName: candidate.sheetName,
+    });
+    // The cache is an optimization, never a gate: a durable backing store that
+    // throws on read must not block resolution.
+    const cached = cacheGet(options.cache, cacheKey);
+    if (cached)
+        return cached;
+    let raw;
+    try {
+        raw = await callLlmWithTimeout(options.llm, { prompt, promptHash }, options.timeoutMs);
+    }
+    catch {
+        return { ...heuristic, downgradeReason: "llm_unavailable" };
+    }
+    // Validate against the rendered window, not the full row count: the model can
+    // only legitimately pick a row it was shown.
+    const windowRowCount = Math.min(candidate.rows.length, ESCALATION_ROW_WINDOW);
+    const submission = parseHeaderSubmission(raw, windowRowCount);
+    if (!submission) {
+        return { ...heuristic, downgradeReason: "invalid_submission" };
+    }
+    const resolved = {
+        sheetName: candidate.sheetName,
+        headerRowIndex: submission.header_row_index,
+        confidence: "high",
+        source: "llm",
+    };
+    // A cache write failure (full disk, permissions) must not reject a valid
+    // resolution — replay support cannot change resolution availability.
+    cacheSet(options.cache, cacheKey, resolved);
+    return resolved;
+}
+function cacheGet(cache, key) {
+    try {
+        return cache?.get(key);
+    }
+    catch {
+        return undefined;
+    }
+}
+function cacheSet(cache, key, value) {
+    try {
+        cache?.set(key, value);
+    }
+    catch {
+        // non-fatal: the resolution is still returned.
+    }
+}