onto-mcp 0.4.11 → 0.4.13

package/dist/core-runtime/reconstruct/execution-telemetry.js

@@ -11,6 +11,8 @@
  * telemetry value.
  */
 import crypto from "node:crypto";
+import { witnessedReconstructRouteIdentity, } from "../route-identity.js";
+import { readStructuredDispatchFailureEvidence } from "../llm/structured-dispatch-error.js";
 /**
  * Maps authored-artifact names (the `artifactName` passed to the JSON author
  * call) to the pipeline unit that owns the call. Repair and timeout-recovery
@@ -19,6 +21,17 @@ import crypto from "node:crypto";
  */
 const UNIT_ID_BY_AUTHORED_ARTIFACT_NAME = new Map([
     ["SourceObservationDirective", "observation_directive"],
+    // P1-C2 leaf-read (the first LLM-touch). Its absence here was the defect: callLlmRecorded
+    // (run.ts) resolves the unit as its first line, BEFORE the LLM call, so an unmapped name throws
+    // and the leaf-read caller swallowed it (R9) → zero capture, silently. Mapped to its own unit so
+    // leaf-read attempts/failures are recorded, not silently degraded.
+    ["leaf-read", "leaf_read"],
+    // Layer-2 semantic_map stage (wiring design 20260702 §6 F5, Defect-1 discipline): BOTH author
+    // capability call names are mapped BEFORE any author realization lands — an unmapped
+    // callJsonAuthor artifactName throws pre-LLM and silently kills the whole stage (the leaf-read
+    // production defect this map's fail-loud contract exists to prevent).
+    ["semantic-map-synthesize", "semantic_map"],
+    ["semantic-map-verify", "semantic_map"],
     ["ExplorationSynthesis", "exploration_synthesis"],
     ["SourceFrontier", "source_frontier"],
     ["SourcePurposeCandidates", "source_purpose_candidates"],
@@ -38,9 +51,16 @@ const UNIT_ID_BY_AUTHORED_ARTIFACT_NAME = new Map([
     ["FailureClassification", "failure_classification"],
     ["RevisionProposal", "revision_proposal"],
     ["StopDecision", "stop_decision"],
+    // Maturation value-read cut (the second LLM-touch). Both authoring calls (location
+    // selection + discharge judgment) own the single maturation_value_read unit, so a
+    // value-read total-failure is recorded, not silently degraded (leaf_read precedent —
+    // an unmapped name throws in callLlmRecorded before the LLM call).
+    ["MaturationValueReadLocation", "maturation_value_read"],
+    ["MaturationValueReadJudgment", "maturation_value_read"],
     ["MaturationQuestionFrontier", "maturation_question_frontier"],
     ["MaturationClosureFrontier", "maturation_closure_frontier"],
     ["AnswerSupportLedger", "answer_support_ledger"],
+    ["AnswerSupportJudgment", "answer_support_judgment"],
     ["MaturationAnswerClaims", "maturation_answer_claims"],
     ["OntologyExpansion", "ontology_expansion"],
     ["FinalOutput", "final_output"],
@@ -74,6 +94,11 @@ export function attemptKindForAuthoredArtifactName(artifactName) {
     return "initial";
 }
 export function failureClassForLlmCallError(error, isTimeout) {
+    const structured = readStructuredDispatchFailureEvidence(error);
+    if (structured?.failure_class === "transport" &&
+        structured.failure_code === "timeout") {
+        return "timeout";
+    }
     return isTimeout(error) ? "timeout" : "provider_error";
 }
 function sha256Hex(text) {
@@ -84,8 +109,9 @@ function addSourceIdentityRef(row, ref) {
         row.source_identity_refs.push(ref);
     }
 }
-export function createReconstructExecutionTelemetryCollector() {
+export function createReconstructExecutionTelemetryCollector(options = {}) {
     const byUnitId = new Map();
+    const routeProjectionByUnitId = new Map();
     function unitRow(unitId) {
         const existing = byUnitId.get(unitId);
         if (existing)
@@ -101,6 +127,7 @@ export function createReconstructExecutionTelemetryCollector() {
             provider_route: null,
             model_id: null,
             effort: null,
+            route_identity: null,
             prompt_policy_sha256: null,
             source_identity_refs: [],
             attempt_count: 0,
@@ -117,19 +144,66 @@ export function createReconstructExecutionTelemetryCollector() {
             row.duration_ms += Math.max(0, Math.round(input.durationMs));
             row.prompt_chars += Math.max(0, input.promptChars);
             row.output_chars += Math.max(0, input.outputChars);
-            if (typeof input.providerTokensIn === "number" && input.providerTokensIn > 0) {
+            if (typeof input.providerTokensIn === "number" && input.providerTokensIn >= 0) {
                 row.provider_tokens_in = (row.provider_tokens_in ?? 0) + input.providerTokensIn;
             }
-            if (typeof input.providerTokensOut === "number" && input.providerTokensOut > 0) {
+            if (typeof input.providerTokensOut === "number" && input.providerTokensOut >= 0) {
                 row.provider_tokens_out =
                     (row.provider_tokens_out ?? 0) + input.providerTokensOut;
             }
-            if (input.providerRoute)
-                row.provider_route = input.providerRoute;
-            if (input.modelId)
-                row.model_id = input.modelId;
-            if (input.effort)
-                row.effort = input.effort;
+            const routeIdentity = input.provider || input.executionAdapter || input.effectiveBaseUrl
+                ? witnessedReconstructRouteIdentity({
+                    provider: input.provider,
+                    executionAdapter: input.executionAdapter,
+                    declaredBillingMode: input.declaredBillingMode,
+                    effectiveBaseUrl: input.effectiveBaseUrl,
+                })
+                : null;
+            const hasRouteProjection = Boolean(input.providerRoute || input.modelId || input.effort || routeIdentity);
+            if (hasRouteProjection && !options.nullMixedRouteProjection) {
+                if (input.providerRoute)
+                    row.provider_route = input.providerRoute;
+                if (input.modelId)
+                    row.model_id = input.modelId;
+                if (input.effort)
+                    row.effort = input.effort;
+                if (routeIdentity)
+                    row.route_identity = routeIdentity;
+            }
+            else if (hasRouteProjection) {
+                const projection = routeProjectionByUnitId.get(input.unitId) ?? {
+                    providerRoute: null,
+                    modelId: null,
+                    effort: null,
+                    routeIdentity: null,
+                    mixed: false,
+                };
+                const conflicts = (prior, next) => prior !== null &&
+                    next !== null &&
+                    JSON.stringify(prior) !== JSON.stringify(next);
+                projection.mixed = projection.mixed ||
+                    conflicts(projection.providerRoute, input.providerRoute ?? null) ||
+                    conflicts(projection.modelId, input.modelId ?? null) ||
+                    conflicts(projection.effort, input.effort ?? null) ||
+                    conflicts(projection.routeIdentity, routeIdentity);
+                projection.providerRoute ??= input.providerRoute ?? null;
+                projection.modelId ??= input.modelId ?? null;
+                projection.effort ??= input.effort ?? null;
+                projection.routeIdentity ??= routeIdentity;
+                routeProjectionByUnitId.set(input.unitId, projection);
+                if (!projection.mixed) {
+                    row.provider_route = projection.providerRoute;
+                    row.model_id = projection.modelId;
+                    row.effort = projection.effort;
+                    row.route_identity = projection.routeIdentity;
+                }
+                else {
+                    row.provider_route = null;
+                    row.model_id = null;
+                    row.effort = null;
+                    row.route_identity = null;
+                }
+            }
             if (row.prompt_policy_sha256 === null &&
                 input.kind === "initial" &&
                 typeof input.systemPrompt === "string") {
@@ -173,6 +247,7 @@ export function createReconstructExecutionTelemetryCollector() {
         },
         reset() {
             byUnitId.clear();
+            routeProjectionByUnitId.clear();
         },
     };
 }

package/dist/core-runtime/reconstruct/final-output-sections.js

@@ -0,0 +1,89 @@
+/**
+ * Single source of truth for the reconstruct final-output append-section set (G(c)).
+ *
+ * The final output emits a fixed set of markdown sections. Their identity (section_id,
+ * heading, prompt-policy id, emission ownership, provenance-binding requirement,
+ * activation) used to be scattered across run.ts in up to FOUR copies per section — the
+ * emitter fn's inline `## <Heading>` literal, the provenance binding's `heading` field, the
+ * prompt-policy `deterministic_runtime_append_sections` hint, and (for the bindings section)
+ * the `required_fragments` section-id literal. This module is the one place that identity
+ * lives; run.ts consumes it for ALL of those representations, and the G9 parity guard
+ * (scripts/check-final-output-sections-parity.ts, INV-SCHEMA-1) asserts the registry node
+ * `final_output_append_sections` declares exactly this surface. Side-effect-free.
+ *
+ * Headings are BARE (no `## ` prefix): run.ts prepends `## ` at the emit site, and the
+ * provenance gate matches on `## ` + heading (post-seed-validation.ts via markdown-section).
+ *
+ * Two ORDERS that differ today are pinned INDEPENDENTLY here (neither derived from the other):
+ *   - the prompt-policy order (claim before artifact) — PROMPT_POLICY_APPEND_SECTION_IDS;
+ *   - the provenance-bindings order (artifact before claim) — the bound-row order of
+ *     FINAL_OUTPUT_SECTIONS, exposed via provenanceBindingSectionIds().
+ */
+/** Canonical hyphen section ids (also the load-bearing required_fragments text). */
+export const FINAL_OUTPUT_SECTION_IDS = {
+    seedAnswerability: "seed-answerability",
+    claimProjection: "claim-projection",
+    artifactTruth: "artifact-truth",
+    runtimeArtifactTruthFooter: "runtime-artifact-truth-footer",
+    runtimeProvenanceBindings: "runtime-provenance-bindings",
+    sourceProjectionTruncation: "source-projection-truncation",
+    workbookInventoryProjectionTruncation: "workbook-inventory-projection-truncation",
+    unresolvedRevisionProposals: "unresolved-revision-proposals",
+};
+/** Bare section headings (no `## ` prefix). The emit site prepends `## `. */
+export const FINAL_OUTPUT_SECTION_HEADINGS = {
+    seedAnswerability: "Seed Answerability",
+    claimProjection: "Claim Projection",
+    artifactTruth: "Artifact Truth",
+    runtimeArtifactTruthFooter: "Runtime Artifact Truth Footer",
+    runtimeProvenanceBindings: "Runtime Provenance Bindings",
+    sourceProjectionTruncation: "Source Projection Truncation",
+    workbookInventoryProjectionTruncation: "Workbook Inventory Projection Truncation",
+    unresolvedRevisionProposals: "Unresolved Revision Proposals",
+};
+const ID = FINAL_OUTPUT_SECTION_IDS;
+const H = FINAL_OUTPUT_SECTION_HEADINGS;
+/**
+ * Canonical ordered descriptors. The 5 bound rows are in the PROVENANCE-BINDINGS order
+ * (artifact before claim) — this is the order finalOutputProvenanceSectionBindings emits and
+ * the order persisted into the validation artifact, so it is load-bearing and must be
+ * preserved. The 3 conditional rows follow in emit order.
+ */
+export const FINAL_OUTPUT_SECTIONS = [
+    { section_id: ID.seedAnswerability, heading: H.seedAnswerability, prompt_policy_id: "seed_answerability", emit_owner: "always_section", provenance_binding_required: true, activation: "always" },
+    { section_id: ID.artifactTruth, heading: H.artifactTruth, prompt_policy_id: "artifact_truth", emit_owner: "always_section", provenance_binding_required: true, activation: "always" },
+    { section_id: ID.claimProjection, heading: H.claimProjection, prompt_policy_id: "claim_projection", emit_owner: "always_section", provenance_binding_required: true, activation: "always" },
+    { section_id: ID.runtimeArtifactTruthFooter, heading: H.runtimeArtifactTruthFooter, prompt_policy_id: "provenance_footer", emit_owner: "always_section", provenance_binding_required: true, activation: "always" },
+    { section_id: ID.runtimeProvenanceBindings, heading: H.runtimeProvenanceBindings, prompt_policy_id: "provenance_bindings", emit_owner: "always_section", provenance_binding_required: true, activation: "always" },
+    { section_id: ID.sourceProjectionTruncation, heading: H.sourceProjectionTruncation, prompt_policy_id: null, emit_owner: "conditional_markdown", provenance_binding_required: false, activation: "document_projection_truncation_nonempty" },
+    { section_id: ID.workbookInventoryProjectionTruncation, heading: H.workbookInventoryProjectionTruncation, prompt_policy_id: null, emit_owner: "conditional_markdown", provenance_binding_required: false, activation: "workbook_inventory_projection_truncation_nonempty" },
+    { section_id: ID.unresolvedRevisionProposals, heading: H.unresolvedRevisionProposals, prompt_policy_id: null, emit_owner: "conditional_markdown", provenance_binding_required: false, activation: "disclosed_revision_proposals_nonempty" },
+];
+/**
+ * The prompt-policy `deterministic_runtime_append_sections` order (claim BEFORE artifact) —
+ * pinned independently of the bindings order. Its SET must equal the non-null
+ * prompt_policy_id set of FINAL_OUTPUT_SECTIONS (asserted by the G9 guard); its ORDER is the
+ * frozen current prompt surface (asserted byte-for-byte by an exact-ordered run.test.ts test).
+ */
+export const PROMPT_POLICY_APPEND_SECTION_IDS = [
+    "seed_answerability",
+    "claim_projection",
+    "artifact_truth",
+    "provenance_footer",
+    "provenance_bindings",
+];
+export function promptPolicyAppendSectionIds() {
+    return [...PROMPT_POLICY_APPEND_SECTION_IDS];
+}
+/** The bound section_ids in provenance-bindings order (artifact before claim). */
+export function provenanceBindingSectionIds() {
+    return FINAL_OUTPUT_SECTIONS.filter((s) => s.provenance_binding_required).map((s) => s.section_id);
+}
+/**
+ * The runtime-provenance-bindings section's required_fragments: the OTHER bound section_ids
+ * (every bound section except runtime-provenance-bindings itself), in bindings order. Derived
+ * here so the load-bearing validated-text list cannot drift from the canonical set.
+ */
+export function runtimeProvenanceBindingsRequiredFragments() {
+    return provenanceBindingSectionIds().filter((id) => id !== FINAL_OUTPUT_SECTION_IDS.runtimeProvenanceBindings);
+}

package/dist/core-runtime/reconstruct/governing-snapshot.js

@@ -6,6 +6,7 @@ import { parse as parseYaml } from "yaml";
 import { resolveRegistryRef, } from "./contract-registry.js";
 import { isPathInsideRoot, } from "../path-boundary.js";
 import { assertReconstructDomainId, } from "./domain-id.js";
+import { assertObligation } from "./obligation-assertion.js";
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -300,6 +301,25 @@ async function buildAdmittedDomainSnapshots(args) {
     }
     return snapshots;
 }
+/**
+ * The exact field allow-list embedded in the `validator_records` governing-snapshot
+ * family (and therefore in the authored-artifact reuse hash). The loader preserves
+ * additional fields on a parsed validator record (e.g. validation_obligations,
+ * conditional_validation_obligations) so callers can read them, but those MUST NOT
+ * enter the snapshot/reuse hash or every prior authored artifact would be forced to
+ * re-author. This is an ALLOW-LIST, not a strip-list: any future parsed field is
+ * excluded by default and must be consciously added here to enter the snapshot, so
+ * the no-rotation guarantee holds for the whole field class, not just today's two.
+ */
+export function projectValidatorRecordSnapshotFields(validator) {
+    return {
+        validator_id: validator.validator_id,
+        gate_ids: validator.gate_ids,
+        validator_version: validator.validator_version,
+        input_authority_refs: validator.input_authority_refs,
+        output_ref: validator.output_ref,
+    };
+}
 function snapshotFamily(args) {
     const items = Array.isArray(args.value) ? args.value : [];
     return {
@@ -409,7 +429,10 @@ export async function buildReconstructRunGoverningSnapshot(args) {
             snapshotFamily({
                 familyId: "validator_records",
                 sourceRef: "reconstruct-contract-registry.yaml#validator_records",
-                value: args.contractRegistry.validator_records,
+                // Allow-list projection: obligation fields the loader now preserves are
+                // excluded so the family sha (and the reuse hash it feeds) stays byte-identical.
+                value: args.contractRegistry.validator_records
+                    .map(projectValidatorRecordSnapshotFields),
                 selectedIds: args.contractRegistry.validator_records
                     .map((validator) => validator.validator_id),
             }),
@@ -601,6 +624,18 @@ export async function validateReconstructRunGoverningSnapshot(args) {
         ];
     }
     const violations = [];
+    // Reached only when the registry hash matched: the per-field equality comparisons below now run, so
+    // record the four snapshot-freeze obligations whose named scope maps 1:1 to a non-shared per-field
+    // check and is fully entailed by equality to the authority projection (selected ids == registry ids
+    // → resolve; version/snapshot map carries an entry per selected id → recorded). The pattern-catalog
+    // canonical-URI obligation is intentionally NOT stamped here: the rebuild derives the URI from a fixed
+    // URN convention of the id and never reads the registry canonical_uri_policy it names (PARKED).
+    if (args.assertedObligationIds) {
+        assertObligation(args.assertedObligationIds, "selected_reference_standard_ids_resolve_to_reference_standard_registry");
+        assertObligation(args.assertedObligationIds, "selected_reference_standard_versions_or_snapshots_are_recorded");
+        assertObligation(args.assertedObligationIds, "selected_pattern_catalog_ids_resolve_to_reference_pattern_catalog_registry");
+        assertObligation(args.assertedObligationIds, "selected_pattern_catalog_versions_or_snapshots_are_recorded");
+    }
     const checks = [
         {
             subject: "governing_snapshot.registry",

package/dist/core-runtime/reconstruct/leaf-reader.js

@@ -0,0 +1,305 @@
+import { createHash } from "node:crypto";
+import { compareColumnResidualDesc, } from "../spreadsheet-structure-observer.js";
+import { LEAF_SEMANTIC_ROLES, } from "./comprehension-artifact.js";
+import { readReconstructLlmDispatchFailureError } from "./llm-dispatch-failure.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// leaf-reader (§3.2 / P1-C2-A · P1-C2-B′) — the FIRST LLM-touch. For a region the deterministic
+// observer could not fully capture — a low-confidence (unstructured) region, OR a high-confidence
+// column whose structure is incomplete (P1-C2-B′ §3) — the leaf-reader asks the LLM to CAPTURE what
+// structure missed: a provisional label, an optional analytical role, and an optional note on the
+// structure/meaning the aggregate signatures reveal.
+//
+// Honesty (§2.2/§2.3):
+//  - The label/role/note TEXT is the LLM's only contribution. The confidence tags are DETERMINISTIC:
+//    the read is always forced confidence='low' and is_lower_bound=true — the LLM cannot claim a
+//    strong reading on a structurally weak region (graceful degrade, non-authoritative).
+//  - Input is bounded deterministic structural metadata: value-tile shapes/format-identities,
+//    header-candidate rows, and (for a resolved high-confidence column) the deterministic column
+//    HEADER LABEL + inferred type/distinct count. NO raw DATA cell values and no literal formatCodes
+//    reach the LLM (source-safety, P1-C1 §3.4). The header label is column IDENTITY (already visible
+//    to the authoring LLM via the inventory), not row data; PII/value redaction is out of scope by
+//    owner governance. So `captured_note` is free LLM text but is grounded ONLY on these aggregate
+//    signals + the header label — it has no raw data value to restate.
+//  - Localization stays grounded on the deterministic value-tile (degrade is naming-only); a wrong
+//    label cannot corrupt correlation because this cut feeds no reduce/merge.
+//  - Failure (LLM hard error) and empty reads are explicit outcomes, never a silent success (§11 R9).
+//
+// This module is LLM-caller-injected (`callLlm`) so it is exercised by the INV-MOCK-1 fixture in
+// tests and the real authoring caller in production; the module itself is realization-agnostic.
+// ─────────────────────────────────────────────────────────────────────────────
+/** Single-source leaf-read prompt template. Registered in the authoring-prompt catalog (CG-1) so an
+ *  edit rotates the resume key; also hashed into the llm_touch_fingerprint ⓑ (leaf_prompt_sha256).
+ *  The opening line is the mock dispatcher's stable key — keep it stable when editing the body. */
+export const LEAF_READ_SYSTEM_PROMPT = [
+    "Read provisional column labels for a low-confidence spreadsheet region.",
+    "",
+    "You are given bounded, aggregate-only evidence about spreadsheet columns the deterministic",
+    "observer could NOT fully capture — either a region whose header could not be resolved",
+    "(low-confidence), or a high-confidence column whose structure is incomplete (free-text or",
+    "high-residual content the deterministic summary does not pin down). The evidence is value-shape /",
+    "display-format signatures, the rows where a signature changes, candidate header row indices, and —",
+    "for a resolved column — the deterministic column HEADER LABEL / inferred type / distinct count. You",
+    "are NOT given raw DATA cell values: the header label is column identity, not row data.",
+    "",
+    "For each column you can read, return:",
+    " - tentative_label: a SHORT label naming what the column most likely holds;",
+    ' - semantic_role (optional): one of "category" | "measure" | "identifier" | "free_text" |',
+    '   "reference" — a SINGLE-COLUMN guess from the signals; "identifier"/"reference" are tentative',
+    "   hints only (relationships are judged downstream, not here);",
+    " - captured_note (optional): a SHORT note on structure or meaning the signatures reveal that the",
+    "   deterministic summary did not (e.g. a hidden grouping, or what a format boundary signifies).",
+    "Omit a column you cannot read rather than guessing. Return STRICT JSON:",
+    '{ "labels": [{ "column_index": <int>, "tentative_label": "<short label>",',
+    '              "semantic_role": "<role>"?, "captured_note": "<short note>"? }],',
+    '  "unread_columns": [{ "column_index": <int>, "reason": "<why unreadable>" }] }',
+    "",
+    "Your reads are provisional and non-authoritative; the runtime tags every read low-confidence.",
+    "Base every label, role, and note ONLY on the deterministic signals provided (header label, inferred",
+    "type, distinct count, value-shape/format signatures, boundary rows) — you are given NO raw DATA cell",
+    "values, so a note must never invent or restate a literal data value.",
+].join("\n");
+export function leafReadPromptSha256() {
+    return createHash("sha256").update(LEAF_READ_SYSTEM_PROMPT).digest("hex");
+}
+/**
+ * Derive bounded leaf-read evidence for every LOW-confidence sheet from the deterministic inventory.
+ * Returns one region per low-confidence sheet that has value-tile signal. High-confidence sheets are
+ * left to the deterministic path (no leaf-read). Source-safe by construction (aggregate signatures
+ * + row indices only).
+ */
+export function extractLowConfidenceLeafEvidence(inventory) {
+    const tilesBySheet = new Map();
+    for (const tile of inventory.segmented_value_tiles ?? [])
+        tilesBySheet.set(tile.sheet, tile);
+    const regions = [];
+    for (const sheet of inventory.per_sheet_data ?? []) {
+        if (sheet.header_confidence !== "low")
+            continue;
+        const tile = tilesBySheet.get(sheet.sheet);
+        if (!tile)
+            continue;
+        const columns = tile.columns.map((col) => {
+            const lastSegment = col.segments.length > 0 ? col.segments[col.segments.length - 1] : undefined;
+            return {
+                column_index: col.column_index,
+                dominant_shape: lastSegment ? lastSegment.dominant_shape : null,
+                dominant_format: lastSegment ? lastSegment.dominant_format : null,
+                boundaries: col.intra_tile_notes.map((note) => ({
+                    boundary_kind: note.boundary_kind,
+                    prev_shape: note.prev_shape,
+                    new_shape: note.new_shape,
+                    first_new_format_row: note.first_new_format_row,
+                })),
+            };
+        });
+        if (columns.length === 0)
+            continue;
+        regions.push({
+            sheet: sheet.sheet,
+            trigger: "low_confidence_header",
+            header_candidate_rows: sheet.header_rows ?? [],
+            columns,
+        });
+    }
+    return regions;
+}
+export const DEFAULT_STRUCTURE_LEAF_TRIGGER_OPTS = { max_columns: 64 };
+/**
+ * Deterministic structure-incompleteness trigger (P1-C2-B′ §2.1). Selects leaf-read targets by a
+ * DETERMINISTIC predicate over inventory signals — NOT an LLM judgment of "importance" (which would
+ * make the read-set non-deterministic and reopen DET-1). The reason to read is capture-completeness:
+ * read every column UNLESS structure trivially captures it (a single constant; empty). High-residual
+ * (free-text / content-rich) columns are prioritised; the cap bounds fan-out with an honest capped
+ * census. Low-confidence sheets keep the P1-C2-A guarantee (always read; no regression).
+ *
+ * LLM-free, so the resulting read-set is a pure function of the inventory — the property that makes
+ * the existing resume contract sound (§4).
+ */
+export function extractStructureLeafEvidence(inventory, opts = DEFAULT_STRUCTURE_LEAF_TRIGGER_OPTS) {
+    const tilesBySheet = new Map();
+    for (const tile of inventory.segmented_value_tiles ?? [])
+        tilesBySheet.set(tile.sheet, tile);
+    // (1) Low-confidence sheets: the P1-C2-A read-set — ALWAYS read (no cap, no regression).
+    const lowConfidenceRegions = extractLowConfidenceLeafEvidence(inventory);
+    const lowConfidenceSheets = new Set(lowConfidenceRegions.map((r) => r.sheet));
+    const candidates = [];
+    for (const sheet of inventory.per_sheet_data ?? []) {
+        if (lowConfidenceSheets.has(sheet.sheet))
+            continue; // already fully read by (1)
+        const tile = tilesBySheet.get(sheet.sheet);
+        for (const column of sheet.columns) {
+            if (!isStructureIncomplete(column))
+                continue;
+            candidates.push({ sheet: sheet.sheet, column, tile });
+        }
+    }
+    // Deterministic priority: highest residual (structure summarises LEAST) first.
+    candidates.sort((a, b) => {
+        const r = compareColumnResidualDesc(a.column, b.column);
+        if (r !== 0)
+            return r;
+        return a.sheet < b.sheet ? -1 : a.sheet > b.sheet ? 1 : 0;
+    });
+    const selected = candidates.slice(0, Math.max(0, opts.max_columns));
+    const capped = candidates.slice(Math.max(0, opts.max_columns));
+    // Group selected high-confidence candidates into per-sheet regions (enriched with value-tile
+    // boundary witnesses by column index when available).
+    const bySheet = new Map();
+    for (const { sheet, column, tile } of selected) {
+        let region = bySheet.get(sheet);
+        if (!region) {
+            region = { sheet, trigger: "structure_incomplete", header_candidate_rows: [], columns: [] };
+            bySheet.set(sheet, region);
+        }
+        const tileCol = tile?.columns.find((c) => c.column_index === column.index);
+        const lastSegment = tileCol && tileCol.segments.length > 0 ? tileCol.segments[tileCol.segments.length - 1] : undefined;
+        region.columns.push({
+            column_index: column.index,
+            column_name: column.name,
+            inferred_type: column.inferred_type,
+            distinct_count: column.distinct_count,
+            distinct_is_estimate: column.distinct_count_is_estimate,
+            dominant_shape: lastSegment ? lastSegment.dominant_shape : null,
+            dominant_format: lastSegment ? lastSegment.dominant_format : null,
+            boundaries: (tileCol?.intra_tile_notes ?? []).map((note) => ({
+                boundary_kind: note.boundary_kind,
+                prev_shape: note.prev_shape,
+                new_shape: note.new_shape,
+                first_new_format_row: note.first_new_format_row,
+            })),
+        });
+    }
+    return {
+        regions: [...lowConfidenceRegions, ...bySheet.values()],
+        capped_columns: capped.map((c) => ({
+            sheet: c.sheet,
+            column_index: c.column.index,
+            column_name: c.column.name,
+        })),
+    };
+}
+/** Deterministic "structure trivially captures this column" predicate (P1-C2-B′ §2.1). A column is a
+ *  leaf-read candidate UNLESS structure already says everything: a single constant value, empty, or a
+ *  single uniform formula. (Cost is no concern, so the default leans toward reading — missing a
+ *  capturable fact is the defect to avoid, not an extra read.)
+ *
+ *  Uniform-formula skip (gate follow-up #3): the observer marks `is_uniform_formula` when EXACTLY one
+ *  single-column formula pattern provably covers the column's data cells (a fill-down whose references
+ *  shift but whose structure is one repeated formula; Excel shared-formula dedup collapses these). The
+ *  observer is conservative — a partial-formula / multi-formula / multi-column column is NOT marked, so
+ *  this never wrongly skips. (See InventoryColumn.is_uniform_formula for the residual title-row caveat.) */
+function isStructureIncomplete(column) {
+    if (column.inferred_type === "empty")
+        return false;
+    if (column.non_empty_count === 0)
+        return false;
+    if (column.distinct_count <= 1 && !column.distinct_count_is_estimate)
+        return false; // single constant
+    if (column.is_uniform_formula)
+        return false; // one repeated formula → structure fully captures it (#3)
+    return true;
+}
+/** sha256 of the read-set-shaping LOGIC source (the deterministic trigger: selection + predicate +
+ *  ordering). Folded into the llm_touch_fingerprint ⓑ so editing the read-set logic TAUTOLOGICALLY
+ *  rotates the resume key (CG-1 pattern; [[cg1-catalog-mechanism-decision]]) — NOT relying on a manual
+ *  comprehension_version bump. The read-set is a pure function of the inventory AND this logic: the
+ *  inventory inputs are covered by ⓐ (content_sha256 + adapter_version, which DETERMINE the inventory),
+ *  this covers the logic, and structure_leaf_trigger_config covers the config. Over-rotates on a
+ *  cosmetic source edit (safe: fail toward regenerate, never silent-stale). */
+export function structureLeafTriggerLogicSha256() {
+    const sep = "";
+    return createHash("sha256")
+        .update(extractStructureLeafEvidence.toString())
+        .update(sep)
+        .update(extractLowConfidenceLeafEvidence.toString())
+        .update(sep)
+        .update(isStructureIncomplete.toString())
+        .update(sep)
+        .update(compareColumnResidualDesc.toString())
+        .digest("hex");
+}
+/** Bound on a captured note (the LLM's free-text gist of structure the deterministic summary missed).
+ *  It is derived from aggregate signatures only (no raw cell values reach the LLM), so this caps prose
+ *  length, not source exposure. */
+const MAX_CAPTURED_NOTE_CHARS = 240;
+const LEAF_SEMANTIC_ROLE_SET = new Set(LEAF_SEMANTIC_ROLES);
+/**
+ * Run the LLM leaf-read (CAPTURE) for one region the deterministic observer could not fully capture.
+ * `callLlm` is injected (mock fixture in tests, real authoring caller in production). The LLM
+ * contributes only the label / role / note TEXT; confidence and is_lower_bound are forced (low /
+ * true) regardless of the trigger. An unrecognised semantic_role is dropped (the label is kept);
+ * a captured_note is trimmed and length-bounded.
+ */
+export async function readStructureLeaf(args) {
+    const { evidence, callLlm } = args;
+    let raw;
+    try {
+        raw = await callLlm(LEAF_READ_SYSTEM_PROMPT, {
+            sheet: evidence.sheet,
+            header_candidate_rows: evidence.header_candidate_rows,
+            columns: evidence.columns,
+        });
+    }
+    catch (error) {
+        // Provider output-ceiling failures are run-terminal: partial output must
+        // never enter leaf degradation or permit a later semantic call.
+        if (readReconstructLlmDispatchFailureError(error))
+            throw error;
+        // §11 R9: ordinary transport/provider errors remain explicit FAILED
+        // outcomes and degrade to the deterministic producer.
+        return { kind: "failed", reason: `leaf-read LLM call failed: ${error.message}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { kind: "failed", reason: "leaf-read returned unparseable JSON" };
+    }
+    const rawLabels = Array.isArray(parsed.labels) ? parsed.labels : [];
+    const knownColumns = new Set(evidence.columns.map((c) => c.column_index));
+    const labels = rawLabels
+        .filter((l) => l &&
+        typeof l.column_index === "number" &&
+        knownColumns.has(l.column_index) &&
+        typeof l.tentative_label === "string" &&
+        l.tentative_label.trim() !== "")
+        .map((l) => {
+        // Capture (P1-C2-B′ §3): an unrecognised role is dropped (label kept); a note is trimmed +
+        // length-bounded. The LLM saw only aggregate signatures, so a note carries no raw cell value.
+        const role = typeof l.semantic_role === "string" && LEAF_SEMANTIC_ROLE_SET.has(l.semantic_role)
+            ? l.semantic_role
+            : undefined;
+        const note = typeof l.captured_note === "string" && l.captured_note.trim() !== ""
+            ? l.captured_note.trim().slice(0, MAX_CAPTURED_NOTE_CHARS)
+            : undefined;
+        const label = {
+            sheet: evidence.sheet,
+            column_index: l.column_index,
+            tentative_label: l.tentative_label.trim(),
+            // Forced honesty tags (§2.2): the region is structurally incomplete, so the read is always a
+            // non-authoritative lower bound regardless of any confidence the model asserts.
+            confidence: "low",
+            is_lower_bound: true,
+        };
+        if (role)
+            label.semantic_role = role;
+        if (note)
+            label.captured_note = note;
+        return label;
+    });
+    if (labels.length === 0) {
+        return { kind: "unread", reason: "leaf-read produced no readable labels for this region" };
+    }
+    const limitingReason = evidence.trigger === "structure_incomplete"
+        ? "structure-incomplete region; columns captured provisionally from value-tile signatures"
+        : "low header_confidence region; labels read provisionally from value-tile signatures";
+    return {
+        kind: "produced",
+        result: {
+            labels,
+            limiting_region_ref: `${evidence.sheet}!region`,
+            limiting_reason: limitingReason,
+        },
+    };
+}