onto-mcp 0.4.12 → 0.4.13

package/dist/core-runtime/reconstruct/terminal-validation.js

@@ -3,9 +3,10 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { assertArrayField, atomicWriteYamlDocument as writeYamlDocument } from "../artifact-io.js";
-import { RECONSTRUCT_STAGE_IDS } from "./artifact-types.js";
+import { RECONSTRUCT_STAGE_IDS, WITNESS_LESS_CONDITIONAL_STAGE_IDS } from "./artifact-types.js";
 import { loadReconstructContractRegistry, } from "./contract-registry.js";
 import { validateReconstructRunGoverningSnapshot } from "./governing-snapshot.js";
+import { assertObligation } from "./obligation-assertion.js";
 function isoNow() {
     return new Date().toISOString();
 }
@@ -45,9 +46,13 @@ const SELF_VALIDATION_OUTPUT_REFS = new Set([
     "pre_handoff_run_manifest_validation",
     "post_publication_run_manifest_validation",
 ]);
+// The witness-less conditional stages permitted `skip_kind: "legit_conditional"` on a
+// graceful-terminal manifest (canonical set in artifact-types.ts, shared with the builder).
+const WITNESS_LESS_CONDITIONAL_STAGES = new Set(WITNESS_LESS_CONDITIONAL_STAGE_IDS);
 export async function validateReconstructRunManifest(args) {
     assertArrayField(args.manifest.steps, "run-manifest", "steps");
     const violations = [];
+    const assertedObligationIds = [];
     const stepById = new Map(args.manifest.steps.map((step) => [step.step_id, step]));
     for (const stageId of RECONSTRUCT_STAGE_IDS) {
         if (!stepById.has(stageId)) {
@@ -58,6 +63,27 @@ export async function validateReconstructRunManifest(args) {
             }));
         }
     }
+    // W3 review W3-004: missing-only checking was fail-OPEN for extra/duplicate steps — a
+    // misregistered or duplicated step id validated green. Exact-set both directions.
+    const knownStageIds = new Set(RECONSTRUCT_STAGE_IDS);
+    const seenStepIds = new Set();
+    for (const step of args.manifest.steps) {
+        if (!knownStageIds.has(step.step_id)) {
+            violations.push(violation({
+                code: "manifest_step_unknown",
+                message: `manifest carries unknown stage ${step.step_id}`,
+                subjectId: step.step_id,
+            }));
+        }
+        if (seenStepIds.has(step.step_id)) {
+            violations.push(violation({
+                code: "manifest_step_duplicate",
+                message: `manifest carries duplicate stage ${step.step_id}`,
+                subjectId: step.step_id,
+            }));
+        }
+        seenStepIds.add(step.step_id);
+    }
     for (const step of args.manifest.steps) {
         if (step.status !== "completed")
             continue;
@@ -89,6 +115,17 @@ export async function validateReconstructRunManifest(args) {
         args.contractRegistry &&
         args.selectedSourceProfiles &&
         args.lensIds) {
+        // AUTHORITY-GATED record (slice 28): the governing-snapshot drift check rebuilds the expected
+        // snapshot from the live registry/profile/lens authority and compares each recorded field by exact
+        // value, so it only runs when that authority is supplied. The four recorded snapshot-freeze
+        // obligations (selected reference-standard / pattern-catalog ids resolve to the registry projection;
+        // their version/snapshot maps carry an entry per selected id) are stamped INSIDE the callee, at the
+        // per-field `checks` loop — past the missing-snapshot and registry-hash early-returns — so they
+        // record only when the comparisons actually run. The remaining 23 obligations stay PARKED (see
+        // obligation-coverage-ledger.yaml): shared-field obligations cannot bind a single one, the canonical
+        // URI obligation names a registry policy the rebuild never reads, "allowed/supported/contains" are
+        // enforced at snapshot-build time, the p2/p3 non-promotion policy and governed-seed/previous-id
+        // closures are not compared fields, and the registry ref+hash presence overlaps the hash-match path.
         violations.push(...await validateReconstructRunGoverningSnapshot({
             projectRoot: args.projectRoot,
             registryPath: args.registryPath,
@@ -97,6 +134,7 @@ export async function validateReconstructRunManifest(args) {
             lensIds: args.lensIds,
             admittedDomainIds: args.admittedDomainIds ?? [],
             snapshot: args.manifest.governing_snapshot,
+            assertedObligationIds,
         }));
     }
     else if (!args.manifest.governing_snapshot) {
@@ -106,6 +144,75 @@ export async function validateReconstructRunManifest(args) {
             subjectId: "governing_snapshot",
         }));
     }
+    // Graceful-terminal reachability rules (design v2 §4). Enforced ONLY when the manifest is
+    // an explicit graceful terminal — a completed run has no graceful_terminal field, so this
+    // whole block is skipped and completed-path validation stays byte-identical. Authority for
+    // "did a witness-less conditional stage run and legitimately produce nothing" is an
+    // INDEPENDENT reachability witness (census) read here; the manifest builder cannot
+    // self-declare a legit no-op the witness does not confirm (closes the v1 membership-only hole).
+    if (args.manifest.graceful_terminal) {
+        // legitNoOpByStage: stage -> legit_no_op flag, for witness-less stages that RAN and produced
+        // nothing. ranStages: every witness-less stage the census shows ran (produced or not).
+        const legitNoOpByStage = new Map();
+        const ranStages = new Set();
+        const witnessRef = args.manifest.graceful_terminal.reachability_witness_ref;
+        if (witnessRef) {
+            const census = await readYamlDocumentIfPresent(witnessRef);
+            if (!census) {
+                violations.push(violation({
+                    code: "manifest_reachability_witness_missing",
+                    message: `graceful manifest references a reachability witness that does not exist: ${witnessRef}`,
+                    subjectId: "reachability_witness_ref",
+                }));
+            }
+            else {
+                for (const w of census.stage_witnesses) {
+                    ranStages.add(w.step_id); // present in the census only because the stage ran
+                    if (!w.produced)
+                        legitNoOpByStage.set(w.step_id, w.legit_no_op);
+                }
+            }
+        }
+        for (const step of args.manifest.steps) {
+            if (step.status !== "skipped")
+                continue; // completed already ref-checked; failed out of scope
+            if (step.step_id === "invocation_binding")
+                continue;
+            if (step.skip_kind === undefined) {
+                // M5: a bare skipped step under a graceful terminal is a masking surface (a not-reached
+                // bug hiding as a healthy pre-handoff-style skip). Require the typed discriminant.
+                violations.push(violation({
+                    code: "manifest_untyped_graceful_skip",
+                    message: `graceful manifest skipped step lacks skip_kind: ${step.step_id}`,
+                    subjectId: step.step_id,
+                }));
+                continue;
+            }
+            if (step.skip_kind === "legit_conditional") {
+                // M2: authorized by the WITNESS (ran-and-legit-no-op), not by allowlist membership. Only
+                // the witness-less lineage stages carry this witness; any other stage claiming it, or one
+                // the witness does not confirm ran-and-legit-no-op, is a masking attempt.
+                if (!WITNESS_LESS_CONDITIONAL_STAGES.has(step.step_id) ||
+                    legitNoOpByStage.get(step.step_id) !== true) {
+                    violations.push(violation({
+                        code: "manifest_unwitnessed_conditional_skip",
+                        message: `legit_conditional skip for ${step.step_id} is not confirmed by the reachability witness (must be a witness-less lineage stage that ran and legitimately produced nothing)`,
+                        subjectId: step.step_id,
+                    }));
+                }
+            }
+            else if (step.skip_kind === "not_reached") {
+                // A witness proving the stage RAN contradicts not_reached = masking attempt.
+                if (ranStages.has(step.step_id)) {
+                    violations.push(violation({
+                        code: "manifest_reached_stage_masked",
+                        message: `${step.step_id} is marked not_reached but the reachability witness shows it ran`,
+                        subjectId: step.step_id,
+                    }));
+                }
+            }
+        }
+    }
     const completedStepCount = args.manifest.steps.filter((step) => step.status === "completed").length;
     const skippedStepCount = args.manifest.steps.filter((step) => step.status === "skipped").length;
     return {
@@ -119,6 +226,7 @@ export async function validateReconstructRunManifest(args) {
         validation_results: violations.length === 0
             ? ["reconstruct_run_manifest_valid"]
             : ["reconstruct_run_manifest_invalid"],
+        asserted_obligation_ids: assertedObligationIds,
         violations,
     };
 }
@@ -222,6 +330,10 @@ function validationArtifactStatuses(args) {
             "source-scout-pack-validation.post-maturation.yaml",
             statusOf(args.sourceScoutPackPostMaturationValidation),
         ],
+        [
+            "semantic-map-resume-validation.yaml",
+            statusOf(args.semanticMapResumeValidation),
+        ],
         [
             "material-admission-ledger-validation.yaml",
             statusOf(args.materialAdmissionLedgerValidation),
@@ -796,6 +908,15 @@ export function validateHandoffDecision(args) {
         gate.validation_status,
     ]));
     const violations = [];
+    // G(a) obligation recorder (INV-OBLIGATION-COVERAGE-1): record that control reached the
+    // active-gate consumption loop below. Unconditional, before the per-gate guard so a zero-gate
+    // input still stamps. Only the two ACTIVE-gate obligations are recorded — every PLANNED-gate
+    // obligation is parked because planned_validation_gate_catalog is never loaded into the runtime
+    // registry (projectGateStatusesOnce iterates validation_gate_catalog only); see
+    // obligation-coverage-ledger.yaml.
+    const assertedObligationIds = [];
+    assertObligation(assertedObligationIds, "consume_all_active_validation_gate_statuses_emitted_by_runtime");
+    assertObligation(assertedObligationIds, "project_missing_active_validation_artifact_as_blocked");
     for (const gate of gateProjection) {
         if (gate.applicability === "not_applicable" || gate.applicability === "self_validation_output") {
             continue;
@@ -857,6 +978,7 @@ export function validateHandoffDecision(args) {
         validation_results: violations.length === 0
             ? ["handoff_decision_valid"]
             : ["handoff_decision_invalid"],
+        asserted_obligation_ids: assertedObligationIds,
         violations,
     };
 }
@@ -905,7 +1027,7 @@ export async function writeHandoffDecisionValidationArtifact(args) {
             loadReconstructContractRegistry({ registryPath: args.registryPath }),
     ]);
     const manifest = await readYamlDocumentIfPresent(manifestValidation.reconstruct_run_manifest_ref);
-    const [runControlValidation, registryVerificationEvidenceValidation, targetMaterialProfileValidation, sourceObservationDirectiveValidation, sourceObservationLineageIndexValidation, sourceSafetyLedgerValidation, sourceScoutPackValidation, sourceScoutPackPreSeedValidation, sourceScoutPackPostMaturationValidation, materialAdmissionLedgerValidation, seedAuthoringReadinessValidation, sourceFrontierValidation, sourcePurposeCandidatesValidation, purposeConfirmationValidation, candidateDispositionValidation, ontologySeed, ontologySeedValidation, claimRealizationMapValidation, competencyQuestionsValidation, competencyQuestionAssessment, competencyQuestionAssessmentValidation, seedConfirmationValidation, failureClassificationValidation, revisionProposalValidation,] = await Promise.all([
+    const [runControlValidation, registryVerificationEvidenceValidation, targetMaterialProfileValidation, sourceObservationDirectiveValidation, sourceObservationLineageIndexValidation, sourceSafetyLedgerValidation, sourceScoutPackValidation, sourceScoutPackPreSeedValidation, sourceScoutPackPostMaturationValidation, semanticMapResumeValidation, materialAdmissionLedgerValidation, seedAuthoringReadinessValidation, sourceFrontierValidation, sourcePurposeCandidatesValidation, purposeConfirmationValidation, candidateDispositionValidation, ontologySeed, ontologySeedValidation, claimRealizationMapValidation, competencyQuestionsValidation, competencyQuestionAssessment, competencyQuestionAssessmentValidation, seedConfirmationValidation, failureClassificationValidation, revisionProposalValidation,] = await Promise.all([
         args.runControlValidationPath
             ? readYamlDocumentIfPresent(args.runControlValidationPath)
             : Promise.resolve(null),
@@ -929,6 +1051,9 @@ export async function writeHandoffDecisionValidationArtifact(args) {
         args.sourceScoutPackPostMaturationValidationPath
             ? readYamlDocumentIfPresent(args.sourceScoutPackPostMaturationValidationPath)
             : Promise.resolve(null),
+        args.semanticMapResumeValidationPath
+            ? readYamlDocumentIfPresent(args.semanticMapResumeValidationPath)
+            : Promise.resolve(null),
         args.materialAdmissionLedgerValidationPath
             ? readYamlDocumentIfPresent(args.materialAdmissionLedgerValidationPath)
             : Promise.resolve(null),
@@ -987,6 +1112,7 @@ export async function writeHandoffDecisionValidationArtifact(args) {
             sourceScoutPackPostMaturationValidation
                 ? args.sourceScoutPackPostMaturationValidationPath
                 : null,
+            semanticMapResumeValidation ? args.semanticMapResumeValidationPath : null,
             materialAdmissionLedgerValidation
                 ? args.materialAdmissionLedgerValidationPath
                 : null,
@@ -1043,6 +1169,9 @@ export async function writeHandoffDecisionValidationArtifact(args) {
             "source-scout-pack-validation.post-maturation.yaml": sourceScoutPackPostMaturationValidation
                 ? args.sourceScoutPackPostMaturationValidationPath
                 : null,
+            "semantic-map-resume-validation.yaml": semanticMapResumeValidation
+                ? args.semanticMapResumeValidationPath
+                : null,
             "material-admission-ledger-validation.yaml": materialAdmissionLedgerValidation
                 ? args.materialAdmissionLedgerValidationPath
                 : null,
@@ -1095,6 +1224,7 @@ export async function writeHandoffDecisionValidationArtifact(args) {
         sourceScoutPackValidation,
         sourceScoutPackPreSeedValidation,
         sourceScoutPackPostMaturationValidation,
+        semanticMapResumeValidation,
         materialAdmissionLedgerValidation,
         seedAuthoringReadinessValidation,
         sourceFrontierValidation,

package/dist/core-runtime/review/continuation-plan.js

@@ -1,4 +1,4 @@
-import { isTrustedLedgerUnit } from "../pipeline-execution-ledger.js";
+import { isResolvedLedgerUnit, isTrustedLedgerUnit, } from "../pipeline-execution-ledger.js";
 function lensIdFromUnit(unit) {
     if (unit.unitKind === "lens")
         return unit.unitId;
@@ -21,13 +21,15 @@ function toContinuationUnit(unit, dispatchDecision, reason) {
         reason,
     };
 }
+/** Upstream-satisfied set: trusted outputs plus terminally resolved units
+ * (a demoted unit's downstream consumed the disclosed gap, not its output). */
 function trustedUnitIds(ledger) {
     return new Set(ledger.units
-        .filter((unit) => isTrustedLedgerUnit(unit))
+        .filter((unit) => isResolvedLedgerUnit(unit))
         .map((unit) => unit.unitId));
 }
 function isFrontierUnit(unit, trustedIds) {
-    if (isTrustedLedgerUnit(unit))
+    if (isResolvedLedgerUnit(unit))
         return false;
     return unit.upstreamUnitIds.every((unitId) => trustedIds.has(unitId));
 }
@@ -76,6 +78,11 @@ function targetRejectedUnits(args) {
                 toContinuationUnit(unit, "reject", "Target unit is already trusted and completed; completed outputs are reuse-only."),
             ];
         }
+        if (isResolvedLedgerUnit(unit)) {
+            return [
+                toContinuationUnit(unit, "reject", "Target unit is terminally resolved (demoted complete-with-failure); its gap is disclosed downstream and it owes no further dispatch."),
+            ];
+        }
         if (!args.naturalFrontierUnitIds.has(unitId)) {
             return [
                 toContinuationUnit(unit, "reject", "Target unit is not the current continuation frontier; continue from the earliest untrusted unit first."),
@@ -102,7 +109,7 @@ export function buildReviewContinuationPlan(params) {
     const allRejectedTargets = [...rejectedTargets, ...rejectedMissingFrontierTargets];
     const targetFrontier = requestedTargetSet.size === 0
         ? naturalFrontier
-        : params.ledger.units.filter((unit) => requestedTargetSet.has(unit.unitId) && !isTrustedLedgerUnit(unit));
+        : params.ledger.units.filter((unit) => requestedTargetSet.has(unit.unitId) && !isResolvedLedgerUnit(unit));
     const frontierUnits = allRejectedTargets.length > 0
         ? allRejectedTargets
         : targetFrontier.map((unit) => toContinuationUnit(unit, "run", requestedTargetSet.size === 0
@@ -116,7 +123,7 @@ export function buildReviewContinuationPlan(params) {
         frontierUnitIds,
     });
     const downstreamUnits = params.ledger.units
-        .filter((unit) => downstreamIds.has(unit.unitId) && !isTrustedLedgerUnit(unit))
+        .filter((unit) => downstreamIds.has(unit.unitId) && !isResolvedLedgerUnit(unit))
         .map((unit) => toContinuationUnit(unit, "run", "Downstream unit must be recomputed after the continuation frontier."));
     const preservedArtifactRefs = params.ledger.units
         .filter((unit) => isTrustedLedgerUnit(unit))

package/dist/core-runtime/review/issue-artifact-runtime.js

@@ -3072,7 +3072,10 @@ export async function writeIssueStanceMatrixFromResponses(args) {
         session_id: args.executionPlan.session_id,
         issues,
         validation: {
-            missing_stances: [],
+            missing_stances: (args.demotedLensIds ?? []).map((lensId) => ({
+                lens_id: lensId,
+                reason: "stance_validation_failed",
+            })),
         },
     });
     await validateIssueArtifactOnDisk({

package/dist/core-runtime/review/materializers.js

@@ -7,7 +7,9 @@ import { ensureDirectory, isoNow, normalizeDomainValue, renderReviewTargetMateri
 import { ISSUE_ARTIFACT_IDS, issueArtifactConsumerId, issueArtifactSpec, issueStanceConsumerId, } from "./issue-artifact-runtime.js";
 import { lensSidecarArtifactPath } from "./lens-sidecar-artifact.js";
 import { deliberationResolutionPath } from "./controlled-lens-deliberation.js";
-import { detectTargetMaterialKind, reviewMaterialSupportStatus, } from "../target-material-kind.js";
+import { detectTargetMaterialKind, isSpreadsheetRef, reviewMaterialGoals, reviewMaterialSupportStatus, } from "../target-material-kind.js";
+import { observeSpreadsheetSource, } from "../spreadsheet-structure-observer.js";
+import { computeSpreadsheetDisposition, } from "./spreadsheet-review-disposition.js";
 import { semanticQualityEvidenceForArtifactGeneration } from "./artifact-generation-realization.js";
 /**
  * Load {projectRoot}/.onto/settings.json into the narrow subset used by
@@ -79,7 +81,7 @@ function derivePlanTimeLlmResolution(config) {
         plan.base_url = baseUrl;
     return Object.keys(plan).length > 0 ? plan : undefined;
 }
-function resolveReviewExecutionSettingsForArtifacts(config) {
+export function resolveReviewExecutionSettingsForArtifacts(config) {
     const defaults = defaultReviewExecution();
     const execution = config.review?.execution;
     if (!execution)
@@ -655,6 +657,12 @@ export async function bootstrapInvocationBindingArtifacts(params) {
         effective_boundary_state: effectiveBoundaryState,
         max_concurrent_lenses: maxConcurrentLenses,
         minimum_participating_lenses: params.resolvedLensIds.length,
+        // Stage 1: persist the window-proportional embed budget so the packet stage
+        // reads it without re-resolving. Omitted when unresolved (model-unaware run)
+        // → packet stage falls back to the DEFAULT budget (no regression).
+        ...(params.maxEmbedLines !== undefined
+            ? { max_embed_lines: params.maxEmbedLines }
+            : {}),
     };
     const actorInvocationProfiles = {
         schema_version: "1",
@@ -944,7 +952,7 @@ function requireExecutionPreparationSessionDomain(value) {
     }
     return normalizeDomainValue(value);
 }
-async function buildReviewTargetProfileArtifact(params) {
+async function buildReviewTargetProfileArtifact(params, inventoryByRef, materializedRefs) {
     const sessionRoot = path.resolve(params.sessionRoot);
     const sessionId = path.basename(sessionRoot);
     const resolvedRefs = params.resolvedTargetRefs.map((ref) => path.resolve(ref));
@@ -966,19 +974,82 @@ async function buildReviewTargetProfileArtifact(params) {
         inputKind,
         primaryRole: roles.primary,
     });
+    // SINGLE SOURCE OF TRUTH: one disposition per rendered spreadsheet ref, computed once
+    // over the UNION of resolved + materialized refs from the shared observation. Every
+    // honesty surface below (support_status, target_refs[].inspectable/.sha256, review_goal)
+    // PROJECTS from this map instead of re-deriving "is this workbook backed?" from a proxy.
+    const unionSpreadsheetRefs = uniqueStrings([...resolvedRefs, ...(materializedRefs ?? [])].filter(isSpreadsheetRef));
+    const dispositionByRef = new Map();
+    for (const ref of unionSpreadsheetRefs) {
+        dispositionByRef.set(ref, computeSpreadsheetDisposition(inventoryByRef?.get(ref), ref));
+    }
     const targetRefs = [];
     for (const [index, ref] of resolvedRefs.entries()) {
         const kind = await targetRefKind(ref, sessionRoot);
+        // Per-ref inspectability + sha256 PROJECT from the ref's disposition (spreadsheet-only).
+        // `inspectable` is the renderable-structure axis — a clean data CSV is inspectable even
+        // though it backs no structural obligation. sha256 reuses the single observation's
+        // content hash (no raw re-read; null when the observer declined to read the file).
+        const isSpreadsheet = isSpreadsheetRef(ref);
+        const disposition = isSpreadsheet ? dispositionByRef.get(ref) : undefined;
         targetRefs.push({
             ref,
             role: index === 0 ? "primary" : "supporting",
             kind: kind.kind,
             exists: kind.exists,
             sha256: kind.exists
-                ? await targetRefSha256(ref, kind.kind, params.directoryListingOptions)
+                ? isSpreadsheet
+                    ? (disposition?.sha256 ?? null)
+                    : await targetRefSha256(ref, kind.kind, params.directoryListingOptions)
                 : null,
+            ...(isSpreadsheet
+                ? { inspectable: disposition?.inspectable ?? false }
+                : {}),
         });
     }
+    // SUPPORT-STATUS GATE — projects from the disposition set over the UNION of rendered
+    // spreadsheet refs. It runs UNCONDITIONALLY (not only when the resolved kind is
+    // spreadsheet) because materialized-input renders materializedRefs regardless of the
+    // resolved kind (F1): a code-resolved target carrying a materialized workbook the
+    // observer could not read must not stay `supported`. reviewMaterialSupportStatus is the
+    // KIND-level baseline; any rendered workbook ref that is not inspectable downgrades it to
+    // partial, naming each ref's honest cause (full path, deduped on path+cause).
+    let supportStatus = materialSupport.status;
+    let supportReason = materialSupport.reason;
+    let materialGoals = reviewMaterialGoals(materialDetection.target_material_kind);
+    const unionDispositions = unionSpreadsheetRefs.map((ref) => dispositionByRef.get(ref));
+    const uninspected = unionDispositions.filter((d) => !d.inspectable);
+    if (uninspected.length > 0) {
+        supportStatus = "partial";
+        // Each uninspected disposition carries a non-null `reason` by construction (disposition
+        // invariant: !inspectable ⇒ reason is set); `?? d.ref` only satisfies the string|null
+        // type and is never actually taken.
+        supportReason = `spreadsheet review inspects structure only; ${uninspected.length} of ${unionDispositions.length} workbook ref(s) were not inspected (${uniqueStrings(uninspected.map((d) => d.reason ?? d.ref)).join("; ")})`;
+    }
+    // review_goal spreadsheet obligations = union of backed_goals across the RESOLVED
+    // spreadsheet refs (kind stays the trigger per the approved F1 scope: only support_status
+    // reflects the materialized union). backed_goals is the POSITIVE rule — a goal is carried
+    // only when its specific evidence was rendered for that ref, so an obligation never
+    // outruns its backing (a plain data CSV carries none; a macro-only workbook carries only
+    // access_and_protection_hygiene).
+    if (materialDetection.target_material_kind === "spreadsheet") {
+        materialGoals = uniqueStrings(resolvedRefs
+            .filter(isSpreadsheetRef)
+            .flatMap((ref) => dispositionByRef.get(ref)?.backed_goals ?? []));
+        // No directly-inspectable workbook ref at all — e.g. a directory aggregated as
+        // spreadsheet with no workbook ref, or every ref uninspectable. Nothing backs an
+        // obligation and the render shows only a listing/unsupported note, so a kind-level
+        // `supported` would be dishonest.
+        const anyInspectable = unionDispositions.some((d) => d.inspectable);
+        if (!anyInspectable) {
+            materialGoals = [];
+            if (supportStatus === "supported") {
+                supportStatus = "partial";
+                supportReason =
+                    "spreadsheet target has no directly-inspectable workbook ref (no inventory-backed structural detail rendered)";
+            }
+        }
+    }
     return {
         schema_version: "1",
         session_id: sessionId,
@@ -1000,6 +1071,7 @@ async function buildReviewTargetProfileArtifact(params) {
             ...goalsForRole(roles.primary),
             ...roles.secondary.flatMap(goalsForRole),
             ...domainGoalAdditions(sessionDomain),
+            ...materialGoals,
         ]),
         closure_obligation_policy: [
             "must_close_in_target",
@@ -1012,8 +1084,8 @@ async function buildReviewTargetProfileArtifact(params) {
         material_profile: {
             target_material_kind: materialDetection.target_material_kind,
             target_material_kind_candidates: materialDetection.target_material_kind_candidates,
-            support_status: materialSupport.status,
-            unsupported_reason: materialSupport.reason,
+            support_status: supportStatus,
+            unsupported_reason: supportReason,
             detection: {
                 owner: "runtime_heuristic",
                 confidence: materialDetection.confidence,
@@ -1045,17 +1117,34 @@ export async function materializeReviewExecutionPreparationArtifacts(params) {
     const reviewTargetProfilePath = path.join(executionPreparationRoot, "review-target-profile.yaml");
     const contextCandidateAssemblyPath = path.join(executionPreparationRoot, "context-candidate-assembly.yaml");
     await ensureDirectory(executionPreparationRoot);
+    const resolvedTargetRefs = params.resolvedTargetRefs.map((ref) => path.resolve(ref));
     const materializedRefs = params.materializedRefs && params.materializedRefs.length > 0
         ? params.materializedRefs.map((ref) => path.resolve(ref))
-        : params.resolvedTargetRefs.map((ref) => path.resolve(ref));
+        : resolvedTargetRefs;
+    // Observe each spreadsheet ref ONCE and share the inventory across the profile and
+    // both renders (design §3.2 "single observation"): a workbook would otherwise be
+    // parsed up to three times (target-snapshot + materialized-input + profile
+    // inspectability). The map feeds per-target inspectability and the rendered detail.
+    const spreadsheetRefs = [
+        ...new Set([...resolvedTargetRefs, ...materializedRefs].filter(isSpreadsheetRef)),
+    ];
+    // Observe SEQUENTIALLY (not Promise.all): observeSpreadsheetSource reads each source
+    // fully into a Buffer (up to the 1 GiB pre-read limit) before streaming-unzip, so
+    // observing every ref of a multi-workbook bundle at once could exhaust host memory
+    // before any artifact is written. Sequential keeps peak memory at one workbook while
+    // still observing — and sharing — each inventory exactly once.
+    const inventoryByRef = new Map();
+    for (const ref of spreadsheetRefs) {
+        inventoryByRef.set(ref, await observeSpreadsheetSource(ref));
+    }
     const targetSnapshotManifest = {
         review_target_scope_kind: params.scopeKind,
-        resolved_target_refs: params.resolvedTargetRefs.map((ref) => path.resolve(ref)),
+        resolved_target_refs: resolvedTargetRefs,
         review_target_profile_ref: reviewTargetProfilePath,
         captured_at: isoNow(),
         capture_reason: "prompt-backed review execution",
     };
-    const reviewTargetProfile = await buildReviewTargetProfileArtifact(params);
+    const reviewTargetProfile = await buildReviewTargetProfileArtifact(params, inventoryByRef, materializedRefs);
     const contextCandidateAssembly = {
         system_purpose_refs: params.systemPurposeRefs ?? [],
         domain_context_refs: params.domainContextRefs ?? [],
@@ -1063,10 +1152,10 @@ export async function materializeReviewExecutionPreparationArtifacts(params) {
         execution_rule_refs: params.executionRuleRefs ?? [],
     };
     await Promise.all([
-        fs.writeFile(targetSnapshotPath, await renderTargetSnapshot(params.resolvedTargetRefs.map((ref) => path.resolve(ref)), params.directoryListingOptions), "utf8"),
+        fs.writeFile(targetSnapshotPath, await renderTargetSnapshot(resolvedTargetRefs, params.directoryListingOptions, inventoryByRef, params.inventoryPromptCaps), "utf8"),
         writeYamlDocument(targetSnapshotManifestPath, targetSnapshotManifest),
         writeYamlDocument(reviewTargetProfilePath, reviewTargetProfile),
-        fs.writeFile(materializedInputPath, await renderReviewTargetMaterializedInput(params.materializedKind, materializedRefs, params.directoryListingOptions), "utf8"),
+        fs.writeFile(materializedInputPath, await renderReviewTargetMaterializedInput(params.materializedKind, materializedRefs, params.directoryListingOptions, inventoryByRef, params.inventoryPromptCaps), "utf8"),
         writeYamlDocument(contextCandidateAssemblyPath, contextCandidateAssembly),
     ]);
     return executionPreparationRoot;

package/dist/core-runtime/review/nesting-batch.js

@@ -104,7 +104,7 @@ export function buildNestingBatchScript(descriptor) {
         const auditPath = path.join(outputDir, `.${safeId}.nested-stderr.log`);
         const statRef = `"$TMPDIR/u${index}.status"`;
         const okJson = `{"unit_id":"${jsonEscape(unit.unit_id)}","status":"ok"}`;
-        const failFmt = `{"unit_id":"${jsonEscape(unit.unit_id)}","status":"fail","error":"exit=%s size=%s"}`;
+        const failFmt = `{"unit_id":"${jsonEscape(unit.unit_id)}","status":"fail","error":"exit=%s size=%s log_tail=%s"}`;
         const fallbackJson = `{"unit_id":"${jsonEscape(unit.unit_id)}","status":"fail","error":"no status reported"}`;
         const unitArgs = [
             "--unit-id",
@@ -136,7 +136,11 @@ export function buildNestingBatchScript(descriptor) {
             '  if [ "$EC" = "0" ] && [ "$SIZE" -gt 0 ]; then',
             `    printf '%s' ${shellQuote(okJson)} > ${statRef}`,
             "  else",
-            `    printf ${shellQuote(failFmt)} "$EC" "$SIZE" > ${statRef}`,
+            '    ERROR_HINT=""',
+            '    if [ -f "$LOG" ]; then',
+            `      ERROR_HINT=$(tail -n 20 "$LOG" 2>/dev/null | tr '\\n\\r\\t' '   ' | tr '\\000-\\010\\013\\014\\016-\\037\\177' ' ' | cut -c1-500 | sed 's/\\\\/\\\\\\\\/g; s/"/\\\\"/g')`,
+            "    fi",
+            `    printf ${shellQuote(failFmt)} "$EC" "$SIZE" "$ERROR_HINT" > ${statRef}`,
             "  fi",
             ") &",
         ].join("\n"));