onto-mcp 0.4.11 → 0.4.13

package/dist/core-runtime/reconstruct/post-seed-validation.js

@@ -1,6 +1,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { parse as parseYaml } from "yaml";
+import { atomicWriteYamlDocument as writeYamlDocument } from "../artifact-io.js";
+import { assertObligation } from "./obligation-assertion.js";
 import { ontologySeedClaimProjections, ontologySeedExcludedClaimIds, } from "./seed-claim-projections.js";
 import { collectOntologySeedRefs } from "./ontology-seed-validation.js";
 import { loadReconstructContractRegistry, } from "./contract-registry.js";
@@ -77,6 +79,16 @@ const REVISION_ACTIONS = [
     "reject",
     "defer",
 ];
+// Shared revision-proposal predicates (M4: one blocker predicate used identically at the
+// stop gate (run.ts) and the continuation gate (maturation-validation.ts); both import from
+// here, the revision-proposal concept owner, so the two gates cannot drift). reject|defer
+// block continuation/stop; every non-reuse proposal is disclosed.
+export function isRevisionBlocker(proposal) {
+    return proposal.action === "reject" || proposal.action === "defer";
+}
+export function isRevisionDisclosed(proposal) {
+    return proposal.action !== "reuse";
+}
 function isoNow() {
     return new Date().toISOString();
 }
@@ -162,7 +174,7 @@ function seedLimitationIds(seed) {
         .map((record) => stringField(record, "limitation_id"))
         .filter((id) => id !== null));
 }
-function knownSeedRefs(seed) {
+export function knownSeedRefs(seed) {
     if (!seed)
         return new Set();
     const refs = collectOntologySeedRefs(seed);
@@ -563,6 +575,14 @@ function validateClaimRealizationMapAgainstClaims(args) {
     const seen = new Set();
     const stanceCounts = initCountMap(CLAIM_REALIZATION_STANCES);
     const observations = observationsById(args.sourceObservations);
+    // G(a) slice 7: record the three claim-realization obligations before the per-realization loop so
+    // they are proven wired on a zero-realization map. Each was audited to a distinct enforcement region
+    // (no laundering): require_exactly_one = duplicate_id (in-loop) + missing_required_coverage (the
+    // coverage loop below); claim_ids = unknown_id; evidence_refs = validateEvidenceRef vs source obs.
+    const assertedObligationIds = [];
+    assertObligation(assertedObligationIds, "require_exactly_one_realization_for_each_seed_claim");
+    assertObligation(assertedObligationIds, "validate_realization_claim_ids_against_ontology_seed_claim_ids");
+    assertObligation(assertedObligationIds, "validate_realization_evidence_refs_against_source_observations");
     for (const realization of args.claimRealizationMap.claim_realizations) {
         const subjectId = realization.claim_id;
         if (seen.has(subjectId)) {
@@ -635,6 +655,7 @@ function validateClaimRealizationMapAgainstClaims(args) {
         validation_results: violations.length === 0
             ? ["claim_realization_map_valid"]
             : ["claim_realization_map_invalid"],
+        asserted_obligation_ids: assertedObligationIds,
         violations,
     };
 }
@@ -890,6 +911,41 @@ export function validateCompetencyQuestionsForOntologySeed(args) {
 }
 function validateCompetencyQuestionsAgainstEligibleClaims(args) {
     const violations = [];
+    // G(a) slice 27: record the 9 obligations this validator FULLY enforces with a distinct,
+    // name-matching site. These are the REF-RESOLUTION obligations ("validate X refs against/close-to
+    // authority Y" — every PRESENT ref must resolve to its registry/seed/manifest authority), plus
+    // question-id uniqueness and the exactly-one admitted-competency disposition rule. Authority-backed
+    // stamps are GATED on the authoritative input being supplied (codex #142 R1): the thin
+    // validateCompetencyQuestions path passes no registry/seed/governing-snapshot, so a zero-question
+    // artifact must NOT claim those obligations were enforced against an absent authority. Each stamp is
+    // before the per-question loop so a zero-question set still records once the authority is present; the
+    // enforcement code always runs, only the stamp is gated.
+    // Parked (see obligation-coverage-ledger.yaml notes): emit_required_evidence_scope (PROJECTION_ONLY);
+    // classification_level_axis / hidden_label facet coverage (NOT_FOUND — fields absent); p3-diagnostic
+    // (no code); query/visualization/graph refs (presence-only — codex #142 R1); and — codex #142 R2 — the
+    // 8 *_facet_coverage obligations (presence-only: resolve present facets but never require facets when
+    // the axis is applicable) and validate_required_ontology_handoff_axis_coverage_or_limitation_backed_
+    // disposition (counts inactive/unsupported questions as coverage; no active/limitation-backed filter).
+    const assertedObligationIds = [];
+    // Pure question-set check — enforceable with no external authority.
+    assertObligation(assertedObligationIds, "require_unique_question_id");
+    // Registry-backed ref resolution — only when the contract registry authority is supplied.
+    if (args.contractRegistry) {
+        assertObligation(assertedObligationIds, "validate_coverage_axes_against_coverage_axis_registry");
+        assertObligation(assertedObligationIds, "validate_ontology_handoff_axes_against_ontology_handoff_axis_registry");
+        assertObligation(assertedObligationIds, "validate_reference_standard_refs_against_reference_standard_registry");
+        assertObligation(assertedObligationIds, "validate_pattern_catalog_refs_against_reference_pattern_catalog_registry");
+    }
+    // Seed-backed closure — only when the ontology seed authority is supplied.
+    if (args.ontologySeed) {
+        assertObligation(assertedObligationIds, "validate_seed_ref_refs_close_against_known_seed_refs");
+        assertObligation(assertedObligationIds, "validate_limitation_refs_close_against_handoff_limitations");
+    }
+    // Run-manifest governing-snapshot authority — only when the snapshot is supplied.
+    if (args.governingSnapshot) {
+        assertObligation(assertedObligationIds, "validate_domain_competency_trace_refs_against_run_manifest_context_snapshot");
+        assertObligation(assertedObligationIds, "enforce_admitted_domain_competency_disposition_rule");
+    }
     const normalizedCompetencyQuestions = normalizeCompetencyQuestionsAtBoundary(args.competencyQuestions);
     violations.push(...normalizedCompetencyQuestions.violations);
     const eligibleClaims = new Set(args.eligibleClaimIds);
@@ -1274,11 +1330,36 @@ function validateCompetencyQuestionsAgainstEligibleClaims(args) {
         validation_results: violations.length === 0
             ? ["competency_questions_valid"]
             : ["competency_questions_invalid"],
+        asserted_obligation_ids: assertedObligationIds,
         violations,
     };
 }
 export function validateCompetencyQuestionAssessment(args) {
     const violations = [];
+    // G(a) slice 12: record the three obligations with a distinct, name-matching enforcement site,
+    // stamped unconditionally before the per-assessment / per-question loops so they fire on a
+    // zero-assessment artifact:
+    //   - require_exactly_one_assessment_per_authoritative_question (duplicate_id on a repeat +
+    //     missing_required_coverage when a question has no assessment → exactly one).
+    //   - validate_downstream_effect_consistent_with_answer_status (downstream_effect must equal
+    //     expectedDownstreamEffect(answer_status): invalid_enum).
+    //   - validate_required_seed_refs_close_against_question_seed_refs (bidirectional closure:
+    //     unknown_id for a ref outside the question, missing_required_coverage for a missing one).
+    // PARKED (not recorded), name broader than code — honest declared≠wired, NOT laundered (see
+    // obligation-coverage-ledger.yaml notes):
+    //   - validate_answer_status_against_active_answerability_contract: the validator checks enum
+    //     validity + per-status STRUCTURAL requirements (answerable→evidence_refs/required_seed_refs,
+    //     unsupported/deferred→missing_source_or_confirmation), but never verifies the answer_status
+    //     reflects actual answerability from evidence CONTENT — the answerability judgment is the
+    //     content-blind host-LLM step, not validated here.
+    //   - validate_answerability_trace_refs_close_against_seed_evidence_limitations_and_proofs: there
+    //     is no answerability_trace_refs / limitation_refs / proof_refs field; the validator closes
+    //     only evidence_refs and required_seed_refs (the latter already recorded above), never
+    //     limitations or proofs.
+    const assertedObligationIds = [];
+    assertObligation(assertedObligationIds, "require_exactly_one_assessment_per_authoritative_question");
+    assertObligation(assertedObligationIds, "validate_downstream_effect_consistent_with_answer_status");
+    assertObligation(assertedObligationIds, "validate_required_seed_refs_close_against_question_seed_refs");
     const questionIds = new Set(args.competencyQuestions.questions.map((question) => question.question_id));
     const questionById = new Map(args.competencyQuestions.questions.map((question) => [
         question.question_id,
@@ -1453,6 +1534,7 @@ export function validateCompetencyQuestionAssessment(args) {
         validation_results: violations.length === 0
             ? ["competency_question_assessment_valid"]
             : ["competency_question_assessment_invalid"],
+        asserted_obligation_ids: assertedObligationIds,
         violations,
     };
 }
@@ -1530,7 +1612,25 @@ export function validateFailureClassification(args) {
 }
 export function validateRevisionProposal(args) {
     const violations = [];
+    // Every published proposal is carry-forward scope, so its target must resolve
+    // to a real authority — not just the `failure` case. Claim/question targets
+    // come from the failures' own claim_id/question_id; seed targets from the
+    // ontology-seed's seed_refs (knownSeedRefs). An unresolved target is a
+    // fabricated/stale carry-forward and is rejected as unknown_id.
     const failureIds = new Set(args.failureClassification.failures.map((failure) => failure.failure_id));
+    const failureClaimIds = new Set(args.failureClassification.failures
+        .map((failure) => failure.claim_id)
+        .filter((claimId) => Boolean(claimId)));
+    const failureQuestionIds = new Set(args.failureClassification.failures
+        .map((failure) => failure.question_id)
+        .filter((questionId) => Boolean(questionId)));
+    const seedRefs = knownSeedRefs(args.ontologySeed);
+    const targetAuthorities = {
+        failure: { ids: failureIds, authority: "failure" },
+        claim: { ids: failureClaimIds, authority: "failure claim" },
+        question: { ids: failureQuestionIds, authority: "failure question" },
+        seed: { ids: seedRefs, authority: "ontology-seed seed_ref" },
+    };
     const seen = new Set();
     const actionCounts = initCountMap(REVISION_ACTIONS);
     for (const proposal of args.revisionProposal.proposals) {
@@ -1542,11 +1642,23 @@ export function validateRevisionProposal(args) {
             }));
         }
         seen.add(proposal.proposal_id);
-        if (proposal.target_type === "failure" &&
-            !failureIds.has(proposal.target_id)) {
+        // target_type is the typed union for fresh-authored proposals, but resume /
+        // manual artifact validation loads it from YAML, so a stale value (e.g. the
+        // removed domain_context) can reach here. An unknown type has no authority to
+        // validate against, so reject it as invalid_enum instead of skipping the
+        // authority check and disclosing an unbacked target as carry-forward.
+        const targetAuthority = targetAuthorities[proposal.target_type];
+        if (!targetAuthority) {
+            violations.push(violation({
+                code: "invalid_enum",
+                message: `invalid proposal target_type: ${proposal.target_type}`,
+                subjectId: proposal.proposal_id,
+            }));
+        }
+        else if (!targetAuthority.ids.has(proposal.target_id)) {
             violations.push(violation({
                 code: "unknown_id",
-                message: `proposal references unknown failure: ${proposal.target_id}`,
+                message: `proposal references unknown ${targetAuthority.authority}: ${proposal.target_id}`,
                 subjectId: proposal.proposal_id,
             }));
         }
@@ -1626,10 +1738,6 @@ export function validateFinalOutputProvenance(args) {
     }
     return violations;
 }
-async function writeYamlDocument(filePath, value) {
-    await fs.mkdir(path.dirname(filePath), { recursive: true });
-    await fs.writeFile(filePath, stringifyYaml(value), "utf8");
-}
 async function readYamlDocument(filePath) {
     return parseYaml(await fs.readFile(filePath, "utf8"));
 }
@@ -1690,7 +1798,8 @@ export async function writeCompetencyQuestionsValidationForOntologySeedArtifact(
         readYamlDocument(args.ontologySeedPath),
         readYamlDocument(args.ontologySeedValidationPath),
         readYamlDocument(args.sourceObservationsPath),
-        loadReconstructContractRegistry({ registryPath: args.registryPath }),
+        args.contractRegistry ??
+            loadReconstructContractRegistry({ registryPath: args.registryPath }),
     ]);
     const manifest = args.governingSnapshot || !args.reconstructRunManifestPath
         ? null
@@ -1752,13 +1861,15 @@ export async function writeFailureClassificationValidationArtifact(args) {
     return validation;
 }
 export async function writeRevisionProposalValidationArtifact(args) {
-    const [revisionProposal, failureClassification] = await Promise.all([
+    const [revisionProposal, failureClassification, ontologySeed] = await Promise.all([
         readYamlDocument(args.revisionProposalPath),
         readYamlDocument(args.failureClassificationPath),
+        readYamlDocument(args.ontologySeedPath),
     ]);
     const validation = validateRevisionProposal({
         revisionProposal,
         failureClassification,
+        ontologySeed,
         revisionProposalRef: path.resolve(args.revisionProposalPath),
         failureClassificationRef: path.resolve(args.failureClassificationPath),
     });

package/dist/core-runtime/reconstruct/proof-authority-validation.js

@@ -1,16 +1,12 @@
 import fs from "node:fs/promises";
-import path from "node:path";
-import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { parse as parseYaml } from "yaml";
+import { atomicWriteYamlDocument as writeYamlDocument } from "../artifact-io.js";
 function isoNow() {
     return new Date().toISOString();
 }
 async function readYamlDocument(filePath) {
     return parseYaml(await fs.readFile(filePath, "utf8"));
 }
-async function writeYamlDocument(filePath, value) {
-    await fs.mkdir(path.dirname(filePath), { recursive: true });
-    await fs.writeFile(filePath, stringifyYaml(value), "utf8");
-}
 function violation(args) {
     return {
         code: args.code,

package/dist/core-runtime/reconstruct/purpose-authority-validation.js

@@ -1,6 +1,9 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { parse as parseYaml } from "yaml";
+import { atomicWriteYamlDocument as writeYamlDocument } from "../artifact-io.js";
+import { assertObligation } from "./obligation-assertion.js";
+import { TARGET_MATERIAL_KINDS } from "../target-material-kind.js";
 const PURPOSE_EVIDENCE_KINDS = [
     "P1",
     "P2",
@@ -8,16 +11,18 @@ const PURPOSE_EVIDENCE_KINDS = [
     "P4",
     "P5",
 ];
+const PURPOSE_FRAME_STATUSES = [
+    "source_declared",
+    "evidence_inferred",
+    "limitation_backed",
+    "unresolved",
+];
 function isoNow() {
     return new Date().toISOString();
 }
 async function readYamlDocument(filePath) {
     return parseYaml(await fs.readFile(filePath, "utf8"));
 }
-async function writeYamlDocument(filePath, value) {
-    await fs.mkdir(path.dirname(filePath), { recursive: true });
-    await fs.writeFile(filePath, stringifyYaml(value), "utf8");
-}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -96,6 +101,22 @@ function hasNonEmptyString(value) {
 export function validateSourcePurposeCandidates(args) {
     const artifact = args.sourcePurposeCandidates;
     const violations = [];
+    // G(a) slice 24 — record the obligations this validator FULLY enforces with a distinct violation
+    // (RECORD 6/10). The other 4 stay parked (see obligation-coverage-ledger.yaml notes): derive_
+    // confirmation_required and expose_selected_..._id are PROJECTION-ONLY (computed into the return
+    // object with no violation → no breaching binding); require_purpose_candidate_status_field_to_be_
+    // purpose_source_status is PARTIAL (only the artifact-level alias-field rejection is enforced, no
+    // per-candidate purpose_source_status enum check); and require_exactly_one_primary_..._when_selected
+    // is enforced UNCONDITIONALLY (blind to the "when selected" discriminator the contract scopes it to —
+    // slice-20 superset-blind park). Stamped before any per-candidate guard so the recorder fires on
+    // zero-candidate input.
+    const assertedObligationIds = [];
+    assertObligation(assertedObligationIds, "preserve_contradictions_in_candidate_status_or_limitations");
+    assertObligation(assertedObligationIds, "reject_p5_only_primary_purpose_candidate");
+    assertObligation(assertedObligationIds, "require_mixed_purpose_frame_elements_to_carry_member_scope_refs_member_target_material_kind_member_source_refs_and_cross_material_ref_refs_or_validated_exclusion");
+    assertObligation(assertedObligationIds, "require_non_p1_primary_to_have_two_evidence_kinds_and_one_p2_p3_or_p4");
+    assertObligation(assertedObligationIds, "require_purpose_adequacy_frame_elements_to_have_surface_dimension_facet_and_evidence_or_limitation_state");
+    assertObligation(assertedObligationIds, "validate_purpose_candidate_evidence_refs_against_source_observations");
     const evidenceIndex = observationEvidenceIndex(args.sourceObservations);
     const rawArtifact = artifact;
     if ("source_purpose_status" in rawArtifact || "inference_status" in rawArtifact) {
@@ -220,12 +241,74 @@ export function validateSourcePurposeCandidates(args) {
                 subjectId: candidate.purpose_candidate_id,
             }));
         }
-        if (!Array.isArray(frame.required_elements) || frame.required_elements.length === 0) {
+        // The frame header (frame_kind, frame_status, material_kind_requirements) is required for
+        // every candidate regardless of rank. The direct-call mapper enforces it on the authoring
+        // path; this validator must enforce it on the disk/reuse path (source-purpose-candidates.yaml
+        // is parsed without schema validation) so a malformed frame is never blessed as valid. Only
+        // required_elements is rank-dependent — a rejected candidate may leave it empty (below).
+        if (!hasNonEmptyString(frame.frame_kind)) {
+            violations.push(violation({
+                code: "required_element_missing",
+                message: `${candidatePath}.adequacy_frame.frame_kind must be non-empty`,
+                subjectId: candidate.purpose_candidate_id,
+            }));
+        }
+        if (!PURPOSE_FRAME_STATUSES.includes(frame.frame_status)) {
+            violations.push(violation({
+                code: "invalid_enum",
+                message: `${candidatePath}.adequacy_frame.frame_status is not a valid frame status`,
+                subjectId: candidate.purpose_candidate_id,
+            }));
+        }
+        const requirements = frame.material_kind_requirements;
+        if (typeof requirements !== "object" || requirements === null) {
             violations.push(violation({
                 code: "required_element_missing",
-                message: `${candidatePath}.adequacy_frame.required_elements must not be empty`,
+                message: `${candidatePath}.adequacy_frame.material_kind_requirements is required`,
                 subjectId: candidate.purpose_candidate_id,
             }));
+        }
+        else {
+            if (!TARGET_MATERIAL_KINDS.includes(requirements.target_material_kind)) {
+                violations.push(violation({
+                    code: "invalid_enum",
+                    message: `${candidatePath}.adequacy_frame.material_kind_requirements.target_material_kind is invalid`,
+                    subjectId: candidate.purpose_candidate_id,
+                }));
+            }
+            if (!Array.isArray(requirements.required_facets)) {
+                violations.push(violation({
+                    code: "required_element_missing",
+                    message: `${candidatePath}.adequacy_frame.material_kind_requirements.required_facets must be an array`,
+                    subjectId: candidate.purpose_candidate_id,
+                }));
+            }
+            if (!hasNonEmptyString(requirements.rationale)) {
+                violations.push(violation({
+                    code: "required_element_missing",
+                    message: `${candidatePath}.adequacy_frame.material_kind_requirements.rationale must be non-empty`,
+                    subjectId: candidate.purpose_candidate_id,
+                }));
+            }
+        }
+        if (!Array.isArray(frame.required_elements) || frame.required_elements.length === 0) {
+            // Rejected candidates record a considered-and-excluded alternative for provenance,
+            // not an active adequacy frame, so they may leave required_elements as an empty array
+            // (the full frame header above is still required for every rank). Mirrors the rejected
+            // exemption for supporting evidence. Only the empty-array case is exempt: a non-array
+            // required_elements still violates the artifact contract for every rank, and
+            // non-rejected candidates must still carry frame elements. When a rejected candidate
+            // does provide elements, the element-format checks below still apply.
+            const rejectedEmptyArray = candidate.rank === "rejected" &&
+                Array.isArray(frame.required_elements) &&
+                frame.required_elements.length === 0;
+            if (!rejectedEmptyArray) {
+                violations.push(violation({
+                    code: "required_element_missing",
+                    message: `${candidatePath}.adequacy_frame.required_elements must not be empty`,
+                    subjectId: candidate.purpose_candidate_id,
+                }));
+            }
             continue;
         }
         for (const [elementIndex, element] of frame.required_elements.entries()) {
@@ -292,6 +375,7 @@ export function validateSourcePurposeCandidates(args) {
         validation_results: violations.length === 0
             ? ["source_purpose_candidates_valid"]
             : ["source_purpose_candidates_invalid"],
+        asserted_obligation_ids: assertedObligationIds,
         violations,
     };
 }
@@ -299,6 +383,33 @@ export function validatePurposeConfirmation(args) {
     const confirmation = args.purposeConfirmation;
     const sourceValidation = args.sourcePurposeCandidatesValidation;
     const violations = [];
+    // G(a) slice 11: record the three obligations whose enforcement matches the authoritative contract
+    // (ontology-seeding-and-maturation-design.md §purpose-confirmation; confirmation_required is the
+    // derived inferred/limitation_backed predicate and "the only source for the purpose-confirmation
+    // gate"). All three reach a distinct, name-matching enforcement site below; stamped unconditionally
+    // up front so they fire on any input:
+    //   - validate_confirmation_status_against_selected_purpose_candidate (selected_primary_mismatch
+    //     when purpose_candidate_id != selected_purpose_candidate_id — distinct site).
+    //   - require_confirmation_for_inferred_or_limitation_backed_purpose (when confirmation_required is
+    //     true a non-confirmed status — e.g. not_required — blocks: conflicting_state). Per the contract
+    //     the validator consumes confirmation_required rather than re-deriving inferred/limitation_backed.
+    //   - block_seed_readiness_when_confirmation_is_pending_rejected_unavailable_or_evidence_check_pending
+    //     (each of those statuses blocks seed readiness even when confirmation is not required).
+    // The two former obligations are DISTINCT facets with non-overlapping breaching inputs: ob "require"
+    // is bound by confirmation_required=true + status=not_required (a status not in the "block" list);
+    // ob "block" is bound by confirmation_required=false + status=pending (no confirmation required, yet
+    // it still blocks). PARKED (not recorded), name broader than code — honest declared≠wired, NOT
+    // laundered (see obligation-coverage-ledger.yaml notes):
+    //   - require_revised_confirmation_to_preserve_source_conflict_or_trigger_purpose_discovery_rerun:
+    //     only the rerun arm is enforced (revised_pending_evidence_check → must_rerun_purpose_discovery);
+    //     the "preserve source conflict" arm is never checked — source_conflict_policy is never read.
+    //   - validate_confirmation_status_against_source_purpose_candidate_status_and_validation_confirmation_required:
+    //     the validator reads only sourceValidation.validation_status and confirmation_required, never the
+    //     candidate's own purpose_source_status the name references.
+    const assertedObligationIds = [];
+    assertObligation(assertedObligationIds, "validate_confirmation_status_against_selected_purpose_candidate");
+    assertObligation(assertedObligationIds, "require_confirmation_for_inferred_or_limitation_backed_purpose");
+    assertObligation(assertedObligationIds, "block_seed_readiness_when_confirmation_is_pending_rejected_unavailable_or_evidence_check_pending");
     if (confirmation.session_id !== sourceValidation.session_id) {
         violations.push(violation({
             code: "session_id_mismatch",
@@ -387,6 +498,7 @@ export function validatePurposeConfirmation(args) {
         validation_results: violations.length === 0
             ? ["purpose_confirmation_valid"]
             : ["purpose_confirmation_invalid"],
+        asserted_obligation_ids: assertedObligationIds,
         violations,
     };
 }

package/dist/core-runtime/reconstruct/record.js

@@ -1,7 +1,8 @@
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { parse as parseYaml } from "yaml";
+import { atomicWriteYamlDocument } from "../artifact-io.js";
 const RECORD_ARTIFACT_KEYS = [
     "reconstruct_run_control",
     "reconstruct_run_control_validation",
@@ -14,11 +15,21 @@ const RECORD_ARTIFACT_KEYS = [
     "source_inventory",
     "initial_source_frontier",
     "source_observations",
+    "seed_stage_prompt_source_observations",
     "source_observation_delta",
     "source_observation_delta_validation",
     "source_observation_reentry_validation",
     "source_observation_lineage_index",
     "source_observation_lineage_index_validation",
+    // W3 code review W3-001: normalizeRefs silently DROPS any typed ref key missing from this list —
+    // leaf_read_census was typed on ReconstructRecordArtifactRefs but dropped here (pre-existing
+    // latent type↔behavior mismatch); registered together with the semantic_map refs so the record
+    // (the durable primary evidence artifact) carries what the type declares.
+    "leaf_read_census",
+    "dispatch_incomplete",
+    "semantic_map_census",
+    "semantic_map_sidecar",
+    "semantic_map_resume_validation",
     "source_safety_ledger",
     "source_safety_ledger_validation",
     "source_scout_pack",
@@ -78,6 +89,8 @@ const RECORD_ARTIFACT_KEYS = [
     "maturation_authority_response_validation",
     "answer_support_ledger",
     "answer_support_ledger_validation",
+    "answer_support_judgment",
+    "answer_support_judgment_validation",
     "maturation_answer_claims",
     "maturation_answer_claims_validation",
     "ontology_expansion",
@@ -303,6 +316,30 @@ function buildWarnings(args) {
     }
     return warnings;
 }
+/**
+ * The single canonical terminal-status projection over a reconstruct record (design §16.7).
+ *
+ * "Is this run done, and how?" is judged here and nowhere else: `getRunStatus` (the `status`
+ * field), `deriveReconstructProgress` (liveness / poll interval) and the TUI `deriveWorkflowStatus`
+ * all derive from this one function, so a graceful terminal is treated uniformly as terminal
+ * without each consumer re-checking `record_stage === "completed"` (the removed "diamond").
+ * `terminal_disposition` present ⇒ blocked/limited (terminal, stop polling, NOT "completed");
+ * else the raw `record_stage` ("completed" when the pipeline finished, otherwise in-progress).
+ */
+export function reconstructTerminalStatus(record) {
+    return record.terminal_disposition ?? record.record_stage;
+}
+/**
+ * Record-validator invariant (design §16.7): a graceful terminal never reached the terminal stage,
+ * so `terminal_disposition` and `record_stage === "completed"` are mutually exclusive. Enforced at
+ * the write authority ({@link assembleReconstructRecord}) so no consumer can observe an incoherent
+ * pairing that {@link reconstructTerminalStatus} could not sensibly project.
+ */
+export function assertReconstructTerminalDispositionCoherent(recordStage, terminalDisposition) {
+    if (terminalDisposition && recordStage === "completed") {
+        throw new Error(`reconstruct record invariant: terminal_disposition=${terminalDisposition} cannot pair with record_stage="completed"`);
+    }
+}
 export async function assembleReconstructRecord(params) {
     const sessionRoot = path.resolve(params.sessionRoot);
     const sessionId = path.basename(sessionRoot);
@@ -377,17 +414,25 @@ export async function assembleReconstructRecord(params) {
         stopDecisionPresent: await exists(artifactRefs.stop_decision),
         finalOutputPresent: await exists(artifactRefs.final_output),
     });
+    assertReconstructTerminalDispositionCoherent(recordStage, params.terminalDisposition);
     const record = {
         schema_version: "1",
         reconstruct_record_id: `reconstruct-record:${sessionId}`,
         session_id: sessionId,
         entrypoint: "reconstruct",
         record_stage: recordStage,
+        // Present only on a graceful terminal; conditional spread keeps a normal record byte-identical.
+        ...(params.terminalDisposition
+            ? { terminal_disposition: params.terminalDisposition }
+            : {}),
         created_at: now,
         updated_at: now,
         target_material_kind: targetMaterialProfile?.target_material_kind ?? null,
         support_status: targetMaterialProfile?.support_status ?? null,
         artifact_refs: artifactRefs,
+        ...(params.dispatchFallback && recordStage === "completed"
+            ? { dispatch_fallback: structuredClone(params.dispatchFallback) }
+            : {}),
         artifact_integrity: artifactIntegrity,
         validation_summary: {
             target_material_profile_status: targetMaterialProfileStatus,
@@ -494,6 +539,7 @@ export async function assembleReconstructRecord(params) {
                 "maturation_authority_response",
                 "maturation_authority_response_validation",
                 "answer_support_ledger_validation",
+                "answer_support_judgment_validation",
                 "maturation_answer_claims_validation",
                 "ontology_expansion_validation",
                 "maturation_source_delta",
@@ -536,6 +582,7 @@ export async function assembleReconstructRecord(params) {
                 "maturation_question_frontier",
                 "maturation_closure_frontier",
                 "answer_support_ledger",
+                "answer_support_judgment",
                 "maturation_answer_claims",
                 "ontology_expansion",
                 "final_output",
@@ -556,7 +603,6 @@ export async function assembleReconstructRecord(params) {
     const outputPath = params.outputPath
         ? path.resolve(params.outputPath)
         : path.join(sessionRoot, "reconstruct-record.yaml");
-    await fs.mkdir(path.dirname(outputPath), { recursive: true });
-    await fs.writeFile(outputPath, stringifyYaml(record), "utf8");
+    await atomicWriteYamlDocument(outputPath, record);
     return record;
 }