onto-mcp 0.3.0 → 0.3.2

package/dist/core-runtime/pipeline-execution-ledger.js

@@ -0,0 +1,100 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+export const PIPELINE_EXECUTION_LEDGER_SCHEMA_VERSION = "1";
+export async function fileSha256IfPresent(filePath) {
+    if (!filePath)
+        return null;
+    try {
+        const content = await fs.readFile(filePath);
+        return createHash("sha256").update(content).digest("hex");
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return null;
+        throw error;
+    }
+}
+export async function fileExists(filePath) {
+    if (!filePath)
+        return false;
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function buildOutputHashes(outputRefs) {
+    const entries = await Promise.all(outputRefs.map(async (outputRef) => [
+        outputRef,
+        await fileSha256IfPresent(outputRef),
+    ]));
+    return Object.fromEntries(entries);
+}
+export function hasAllRequiredOutputHashes(unit) {
+    return unit.outputRefs.every((outputRef) => unit.outputHashes[outputRef] !== null);
+}
+export function isTrustedLedgerUnit(unit) {
+    return (unit.status === "completed" &&
+        unit.trustStatus === "trusted" &&
+        hasAllRequiredOutputHashes(unit));
+}
+export function firstUntrustedRequiredUnit(ledger) {
+    return ledger.units.find((unit) => !isTrustedLedgerUnit(unit)) ?? null;
+}
+export function normalizeLedgerRefs(refs) {
+    return [...new Set(refs.filter((ref) => typeof ref === "string" && ref.length > 0))]
+        .sort();
+}
+export function buildLedgerTrust(args) {
+    if (!args.upstreamTrusted) {
+        return {
+            trustStatus: "blocked_by_upstream",
+            trustReason: "A required upstream unit is not trusted.",
+        };
+    }
+    if (args.status === "completed") {
+        const missingOutputRefs = args.outputRefs.filter((outputRef) => args.outputHashes[outputRef] === null);
+        if (missingOutputRefs.length > 0) {
+            return {
+                trustStatus: "untrusted",
+                trustReason: `Completed unit is missing required output refs: ${missingOutputRefs.join(", ")}.`,
+            };
+        }
+        return {
+            trustStatus: "trusted",
+            trustReason: "Unit completed and required output refs are present.",
+        };
+    }
+    if (args.status === "failed") {
+        return {
+            trustStatus: "untrusted",
+            trustReason: args.lastFailureMessage?.trim() ||
+                "Unit failed before producing a trusted output.",
+        };
+    }
+    if (args.status === "skipped") {
+        return {
+            trustStatus: "untrusted",
+            trustReason: "Unit was skipped and did not produce a trusted output.",
+        };
+    }
+    if (args.status === "missing") {
+        return {
+            trustStatus: "untrusted",
+            trustReason: "Required unit output is missing.",
+        };
+    }
+    if (args.status === "not_reached") {
+        return {
+            trustStatus: "blocked_by_upstream",
+            trustReason: "Unit was not reached because upstream execution did not complete.",
+        };
+    }
+    return {
+        trustStatus: "untrusted",
+        trustReason: "Unit is planned but has not completed.",
+    };
+}

package/dist/core-runtime/reconstruct/artifact-types.js

@@ -1 +1,33 @@
-export {};
+export const RECONSTRUCT_STAGE_IDS = [
+    "invocation_binding",
+    "target_material_profile",
+    "source_inventory",
+    "initial_source_frontier",
+    "source_observation",
+    "observation_directive",
+    "observation_directive_validation",
+    "lens_judgment",
+    "exploration_synthesis",
+    "source_frontier",
+    "source_frontier_validation",
+    "domain_context_selection",
+    "domain_context_selection_validation",
+    "seed_candidate",
+    "seed_candidate_validation",
+    "claim_realization",
+    "claim_realization_validation",
+    "seed_confirmation",
+    "seed_confirmation_validation",
+    "competency_questions",
+    "competency_questions_validation",
+    "competency_question_assessment",
+    "competency_question_assessment_validation",
+    "failure_classification",
+    "failure_classification_validation",
+    "revision_proposal",
+    "revision_proposal_validation",
+    "metrics",
+    "stop_decision",
+    "final_output",
+    "record_assembly",
+];

package/dist/core-runtime/reconstruct/materialize-preparation.js

@@ -2,7 +2,7 @@ import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { stringify as stringifyYaml } from "yaml";
-import { detectTargetMaterialKind, } from "../target-material-kind.js";
+import { aggregateTargetMaterialDetections, detectTargetMaterialRefs, } from "../target-material-kind.js";
 import { validateSourceObservationBoundary, } from "./source-observations.js";
 import { loadReconstructSourceProfiles, } from "./source-profiles.js";
 const CONCRETE_TARGET_MATERIAL_KINDS = new Set([
@@ -38,8 +38,8 @@ function supportForMaterial(args) {
     }
     if (args.targetMaterialKind === "mixed") {
         return {
-            support_status: "partial",
-            unsupported_reason: "mixed target material kind requires per-ref observation; unsupported members are skipped",
+            support_status: "partial_composite",
+            unsupported_reason: "mixed target material kind is observed through per-ref source profiles; unsupported members are skipped with authority impact",
         };
     }
     if (args.selectedProfiles.length === 0) {
@@ -91,15 +91,20 @@ function selectedProfileRefs(profiles, candidates) {
 async function textStats(ref) {
     try {
         const text = await fs.readFile(ref, "utf8");
+        const excerptLimit = 6000;
         return {
             line_count: text.length === 0 ? 0 : text.split(/\r?\n/).length,
             char_count: text.length,
+            content_excerpt: text.slice(0, excerptLimit),
+            excerpt_truncated: text.length > excerptLimit,
         };
     }
     catch {
         return {
             line_count: null,
             char_count: null,
+            content_excerpt: null,
+            excerpt_truncated: false,
         };
     }
 }
@@ -113,6 +118,8 @@ async function buildObservation(detection) {
     const stats = stat.isFile() ? await textStats(detection.ref) : {
         line_count: null,
         char_count: null,
+        content_excerpt: null,
+        excerpt_truncated: false,
     };
     const observation = {
         observation_id: stableObservationId({
@@ -132,6 +139,8 @@ async function buildObservation(detection) {
             size_bytes: stat.isFile() ? stat.size : null,
             line_count: stats.line_count,
             char_count: stats.char_count,
+            content_excerpt: stats.content_excerpt,
+            excerpt_truncated: stats.excerpt_truncated,
         },
     };
     const validation = validateSourceObservationBoundary(observation);
@@ -140,6 +149,40 @@ async function buildObservation(detection) {
     }
     return observation;
 }
+function stableFrontierRefId(unit) {
+    const digest = crypto
+        .createHash("sha256")
+        .update(`${unit.target_material_kind}\n${path.resolve(unit.ref)}\n${unit.inventory_unit}`)
+        .digest("hex")
+        .slice(0, 16);
+    return `frontier_initial_${digest}`;
+}
+function buildInitialSourceFrontier(args) {
+    return {
+        schema_version: "1",
+        session_id: args.sessionId,
+        created_at: isoNow(),
+        frontier_id: "initial",
+        source_refs: args.inventory.inventory_units
+            .filter((unit) => unit.scan_status === "planned")
+            .map((unit) => ({
+            frontier_ref_id: stableFrontierRefId(unit),
+            source_ref: unit.ref,
+            target_material_kind: unit.target_material_kind,
+            inventory_unit: unit.inventory_unit,
+            profile_ref: unit.profile_ref,
+            rationale: "Initial source frontier derived from runtime material inventory and selected source profile.",
+        })),
+        skipped_refs: args.inventory.inventory_units
+            .filter((unit) => unit.scan_status === "skipped")
+            .map((unit) => ({
+            source_ref: unit.ref,
+            target_material_kind: unit.target_material_kind,
+            reason: unit.skip_reason ?? "skipped",
+            authority_impact: "Semantic artifacts cannot use this ref as trusted evidence until a supported material profile and observation exist.",
+        })),
+    };
+}
 function buildInventoryUnits(args) {
     return args.detections.map((detection) => {
         const profileRef = profileRefForKind(args.profiles, detection.kind);
@@ -169,7 +212,8 @@ export async function materializeReconstructPreparationArtifacts(params) {
     const sessionId = path.basename(sessionRoot);
     const targetRefs = params.targetRefs.map((ref) => path.resolve(ref));
     const profiles = await loadReconstructSourceProfiles(params.profilesRoot);
-    const detection = await detectTargetMaterialKind(targetRefs);
+    const perRefDetections = await detectTargetMaterialRefs(targetRefs);
+    const detection = aggregateTargetMaterialDetections(perRefDetections);
     const selectedProfiles = selectedProfileRefs(profiles, detection.target_material_kind === "mixed"
         ? detection.target_material_kind_candidates
         : [detection.target_material_kind]);
@@ -207,6 +251,10 @@ export async function materializeReconstructPreparationArtifacts(params) {
             source: "binding",
         },
     };
+    const initialSourceFrontier = buildInitialSourceFrontier({
+        sessionId,
+        inventory,
+    });
     const observations = [];
     const skippedRefs = [];
     for (const unit of inventory.inventory_units) {
@@ -240,11 +288,13 @@ export async function materializeReconstructPreparationArtifacts(params) {
     const refs = {
         target_material_profile: path.join(sessionRoot, "target-material-profile.yaml"),
         source_inventory: path.join(sessionRoot, "source-inventory.yaml"),
+        initial_source_frontier: path.join(sessionRoot, "initial-source-frontier.yaml"),
         source_observations: path.join(sessionRoot, "source-observations.yaml"),
     };
     await Promise.all([
         writeYamlDocument(refs.target_material_profile, targetMaterialProfile),
         writeYamlDocument(refs.source_inventory, inventory),
+        writeYamlDocument(refs.initial_source_frontier, initialSourceFrontier),
         writeYamlDocument(refs.source_observations, sourceObservations),
     ]);
     return refs;

package/dist/core-runtime/reconstruct/pipeline-execution-ledger.js

@@ -0,0 +1,342 @@
+import path from "node:path";
+import { PIPELINE_EXECUTION_LEDGER_SCHEMA_VERSION, buildLedgerTrust, buildOutputHashes, isTrustedLedgerUnit, normalizeLedgerRefs, } from "../pipeline-execution-ledger.js";
+const RECONSTRUCT_LEDGER_STAGE_SPECS = [
+    {
+        unitId: "target_material_profile",
+        unitKind: "material_profile",
+        owner: "runtime",
+        artifactKey: "target_material_profile",
+        upstreamUnitIds: [],
+    },
+    {
+        unitId: "source_inventory",
+        unitKind: "source_inventory",
+        owner: "runtime",
+        artifactKey: "source_inventory",
+        upstreamUnitIds: ["target_material_profile"],
+    },
+    {
+        unitId: "initial_source_frontier",
+        unitKind: "source_frontier_initial",
+        owner: "runtime",
+        artifactKey: "initial_source_frontier",
+        upstreamUnitIds: ["source_inventory"],
+    },
+    {
+        unitId: "source_observation",
+        unitKind: "source_observation",
+        owner: "runtime",
+        artifactKey: "source_observations",
+        upstreamUnitIds: ["initial_source_frontier"],
+    },
+    {
+        unitId: "observation_directive",
+        unitKind: "semantic_directive",
+        owner: "host_llm",
+        artifactKey: "source_observation_directive",
+        upstreamUnitIds: ["source_observation"],
+    },
+    {
+        unitId: "observation_directive_validation",
+        unitKind: "runtime_validation",
+        owner: "runtime",
+        artifactKey: "source_observation_directive_validation",
+        upstreamUnitIds: ["observation_directive"],
+    },
+    {
+        unitId: "domain_context_selection",
+        unitKind: "semantic_context_selection",
+        owner: "host_llm",
+        artifactKey: "domain_context_selection",
+        upstreamUnitIds: ["observation_directive_validation"],
+    },
+    {
+        unitId: "domain_context_selection_validation",
+        unitKind: "runtime_validation",
+        owner: "runtime",
+        artifactKey: "domain_context_selection_validation",
+        upstreamUnitIds: ["domain_context_selection"],
+    },
+    {
+        unitId: "lens_judgment",
+        unitKind: "semantic_lens_judgment",
+        owner: "host_llm",
+        artifactKey: "lens_judgment_index",
+        upstreamUnitIds: ["observation_directive_validation"],
+    },
+    {
+        unitId: "exploration_synthesis",
+        unitKind: "semantic_exploration_synthesis",
+        owner: "host_llm",
+        artifactKey: "exploration_synthesis",
+        upstreamUnitIds: ["lens_judgment"],
+    },
+    {
+        unitId: "source_frontier",
+        unitKind: "semantic_source_frontier",
+        owner: "host_llm",
+        artifactKey: "source_frontier",
+        upstreamUnitIds: ["exploration_synthesis"],
+    },
+    {
+        unitId: "source_frontier_validation",
+        unitKind: "runtime_validation",
+        owner: "runtime",
+        artifactKey: "source_frontier_validation",
+        upstreamUnitIds: ["source_frontier"],
+    },
+    {
+        unitId: "seed_candidate",
+        unitKind: "semantic_seed",
+        owner: "host_llm",
+        artifactKey: "seed_candidate",
+        upstreamUnitIds: ["source_frontier_validation"],
+    },
+    {
+        unitId: "seed_candidate_validation",
+        unitKind: "runtime_validation",
+        owner: "runtime",
+        artifactKey: "seed_candidate_validation",
+        upstreamUnitIds: ["seed_candidate"],
+    },
+    {
+        unitId: "claim_realization",
+        unitKind: "semantic_map",
+        owner: "host_llm",
+        artifactKey: "claim_realization_map",
+        upstreamUnitIds: ["seed_candidate_validation"],
+    },
+    {
+        unitId: "claim_realization_validation",
+        unitKind: "runtime_validation",
+        owner: "runtime",
+        artifactKey: "claim_realization_map_validation",
+        upstreamUnitIds: ["claim_realization"],
+    },
+    {
+        unitId: "seed_confirmation",
+        unitKind: "confirmation",
+        owner: "user_or_host_mediated",
+        artifactKey: "seed_confirmation",
+        upstreamUnitIds: ["seed_candidate_validation", "claim_realization_validation"],
+    },
+    {
+        unitId: "seed_confirmation_validation",
+        unitKind: "runtime_validation",
+        owner: "runtime",
+        artifactKey: "seed_confirmation_validation",
+        upstreamUnitIds: ["seed_confirmation"],
+    },
+    {
+        unitId: "competency_questions",
+        unitKind: "semantic_questions",
+        owner: "host_llm",
+        artifactKey: "competency_questions",
+        upstreamUnitIds: ["seed_confirmation_validation"],
+    },
+    {
+        unitId: "competency_questions_validation",
+        unitKind: "runtime_validation",
+        owner: "runtime",
+        artifactKey: "competency_questions_validation",
+        upstreamUnitIds: ["competency_questions"],
+    },
+    {
+        unitId: "competency_question_assessment",
+        unitKind: "semantic_assessment",
+        owner: "host_llm",
+        artifactKey: "competency_question_assessment",
+        upstreamUnitIds: ["competency_questions_validation"],
+    },
+    {
+        unitId: "competency_question_assessment_validation",
+        unitKind: "runtime_validation",
+        owner: "runtime",
+        artifactKey: "competency_question_assessment_validation",
+        upstreamUnitIds: ["competency_question_assessment"],
+    },
+    {
+        unitId: "failure_classification",
+        unitKind: "semantic_failure_classification",
+        owner: "host_llm",
+        artifactKey: "failure_classification",
+        upstreamUnitIds: ["competency_question_assessment_validation"],
+    },
+    {
+        unitId: "failure_classification_validation",
+        unitKind: "runtime_validation",
+        owner: "runtime",
+        artifactKey: "failure_classification_validation",
+        upstreamUnitIds: ["failure_classification"],
+    },
+    {
+        unitId: "revision_proposal",
+        unitKind: "semantic_revision",
+        owner: "host_llm",
+        artifactKey: "revision_proposal",
+        upstreamUnitIds: ["failure_classification_validation"],
+    },
+    {
+        unitId: "revision_proposal_validation",
+        unitKind: "runtime_validation",
+        owner: "runtime",
+        artifactKey: "revision_proposal_validation",
+        upstreamUnitIds: ["revision_proposal"],
+    },
+    {
+        unitId: "metrics",
+        unitKind: "runtime_metrics",
+        owner: "runtime",
+        artifactKey: "reconstruct_metrics",
+        upstreamUnitIds: ["revision_proposal_validation"],
+    },
+    {
+        unitId: "stop_decision",
+        unitKind: "semantic_decision",
+        owner: "host_llm",
+        artifactKey: "stop_decision",
+        upstreamUnitIds: ["metrics"],
+    },
+    {
+        unitId: "final_output",
+        unitKind: "final_output",
+        owner: "host_llm",
+        artifactKey: "final_output",
+        upstreamUnitIds: ["stop_decision"],
+    },
+    {
+        unitId: "record_assembly",
+        unitKind: "record_assembly",
+        owner: "runtime",
+        artifactKey: "reconstruct_record",
+        upstreamUnitIds: ["final_output"],
+    },
+];
+const VALIDATION_GATE_BY_AUTHORED_UNIT = new Map([
+    ["observation_directive", "observation_directive_validation"],
+    ["source_frontier", "source_frontier_validation"],
+    ["seed_candidate", "seed_candidate_validation"],
+    ["claim_realization", "claim_realization_validation"],
+    ["seed_confirmation", "seed_confirmation_validation"],
+    ["competency_questions", "competency_questions_validation"],
+    ["competency_question_assessment", "competency_question_assessment_validation"],
+    ["failure_classification", "failure_classification_validation"],
+    ["revision_proposal", "revision_proposal_validation"],
+]);
+function artifactRefForKey(args) {
+    if (args.key === "reconstruct_record")
+        return args.reconstructRecordRef ?? null;
+    return args.record.artifact_refs[args.key] ?? null;
+}
+function downstreamMap() {
+    const map = new Map();
+    for (const spec of RECONSTRUCT_LEDGER_STAGE_SPECS)
+        map.set(spec.unitId, []);
+    for (const spec of RECONSTRUCT_LEDGER_STAGE_SPECS) {
+        for (const upstreamUnitId of spec.upstreamUnitIds) {
+            map.set(upstreamUnitId, [...(map.get(upstreamUnitId) ?? []), spec.unitId]);
+        }
+    }
+    return map;
+}
+function manifestStatus(manifest, unitId) {
+    const status = manifest?.steps.find((step) => step.step_id === unitId)?.status;
+    if (status === "completed" || status === "failed" || status === "skipped") {
+        return status;
+    }
+    return null;
+}
+function trustForReconstructUnit(args) {
+    const validationGateUnitId = VALIDATION_GATE_BY_AUTHORED_UNIT.get(args.spec.unitId);
+    if (validationGateUnitId) {
+        const validationOutputPresent = args.artifactRefsByUnitId.get(validationGateUnitId)?.some((ref) => ref.length > 0) ?? false;
+        if (!validationOutputPresent) {
+            return {
+                trustStatus: "untrusted",
+                trustReason: "LLM or user-authored artifact exists only as a candidate until its runtime validation gate completes.",
+            };
+        }
+    }
+    return buildLedgerTrust({
+        status: args.status,
+        outputRefs: args.outputRefs,
+        outputHashes: args.outputHashes,
+        upstreamTrusted: args.upstreamTrusted,
+    });
+}
+export async function buildReconstructPipelineExecutionLedger(params) {
+    const downstreamUnitIds = downstreamMap();
+    const manifestStepByUnitId = new Map((params.reconstructRunManifest?.steps ?? []).map((step) => [step.step_id, step]));
+    const artifactRefsByUnitId = new Map(RECONSTRUCT_LEDGER_STAGE_SPECS.map((spec) => [
+        spec.unitId,
+        normalizeLedgerRefs([
+            artifactRefForKey({
+                key: spec.artifactKey,
+                record: params.reconstructRecord,
+                reconstructRecordRef: params.reconstructRecordRef ?? null,
+            }),
+        ]),
+    ]));
+    const trustedUnitIds = new Set();
+    const units = [];
+    for (const spec of RECONSTRUCT_LEDGER_STAGE_SPECS) {
+        const outputRefs = artifactRefsByUnitId.get(spec.unitId) ?? [];
+        const outputHashes = await buildOutputHashes(outputRefs);
+        const outputPresent = outputRefs.length > 0 &&
+            outputRefs.every((outputRef) => outputHashes[outputRef] !== null);
+        const upstreamTrusted = spec.upstreamUnitIds.every((unitId) => {
+            if (spec.unitKind === "runtime_validation") {
+                return (artifactRefsByUnitId.get(unitId) ?? []).length > 0;
+            }
+            return trustedUnitIds.has(unitId);
+        });
+        const status = manifestStatus(params.reconstructRunManifest, spec.unitId) ??
+            (outputPresent
+                ? "completed"
+                : upstreamTrusted
+                    ? "missing"
+                    : "not_reached");
+        const trust = trustForReconstructUnit({
+            spec,
+            status,
+            outputRefs,
+            outputHashes,
+            upstreamTrusted,
+            artifactRefsByUnitId,
+        });
+        const manifestStep = manifestStepByUnitId.get(spec.unitId);
+        const entry = {
+            unitId: spec.unitId,
+            unitKind: spec.unitKind,
+            owner: spec.owner,
+            producedArtifactRefs: outputRefs,
+            consumedArtifactRefs: normalizeLedgerRefs([
+                ...spec.upstreamUnitIds.flatMap((unitId) => artifactRefsByUnitId.get(unitId) ?? []),
+            ]),
+            outputRefs,
+            outputHashes,
+            status,
+            trustStatus: trust.trustStatus,
+            trustReason: trust.trustReason,
+            attemptCount: manifestStep ? 1 : 0,
+            lastFailureMessage: null,
+            upstreamUnitIds: spec.upstreamUnitIds,
+            downstreamUnitIds: downstreamUnitIds.get(spec.unitId) ?? [],
+        };
+        units.push(entry);
+        if (isTrustedLedgerUnit(entry))
+            trustedUnitIds.add(entry.unitId);
+    }
+    return {
+        schemaVersion: PIPELINE_EXECUTION_LEDGER_SCHEMA_VERSION,
+        pipeline: "reconstruct",
+        sessionId: params.reconstructRecord.session_id || path.basename(params.sessionRoot),
+        sourceRefs: normalizeLedgerRefs([
+            params.reconstructRecordRef,
+            params.reconstructRunManifestRef,
+            ...Object.values(params.reconstructRecord.artifact_refs),
+            ...Object.values(params.reconstructRunManifest?.artifact_refs ?? {}),
+        ]),
+        units,
+    };
+}