onto-mcp 0.4.12 → 0.4.13

package/dist/core-runtime/reconstruct/llm-dispatch-failure.js

@@ -0,0 +1,270 @@
+import crypto from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { z } from "zod";
+import { RECONSTRUCT_STAGE_IDS, } from "./artifact-types.js";
+import { OPENAI_RESPONSES_MAX_OUTPUT_TOKENS_FAILURE_CODE, } from "../llm/openai-responses-incomplete-error.js";
+export const RECONSTRUCT_LLM_DISPATCH_FAILURE_SCHEMA_VERSION = "reconstruct-llm-dispatch-failure/v1";
+export const RECONSTRUCT_LLM_DISPATCH_FAILURE_DIR = "llm-dispatch-failures";
+const ReconstructLlmCallKindSchema = z.enum([
+    "initial",
+    "parse_repair",
+    "semantic_repair",
+    "timeout_recovery",
+]);
+const NullableTokenCountSchema = z.number().int().nonnegative().nullable();
+export const ReconstructLlmDispatchFailureArtifactSchema = z
+    .object({
+    schema_version: z.literal(RECONSTRUCT_LLM_DISPATCH_FAILURE_SCHEMA_VERSION),
+    failure_id: z.string().regex(/^llm-failure:[a-f0-9]{20}$/),
+    session_id: z.string().min(1),
+    created_at: z.string().min(1),
+    owner_attempt_id: z.string().min(1),
+    unit_id: z.enum(RECONSTRUCT_STAGE_IDS),
+    artifact_name: z.string().min(1),
+    call_kind: ReconstructLlmCallKindSchema,
+    failure_code: z.literal(OPENAI_RESPONSES_MAX_OUTPUT_TOKENS_FAILURE_CODE),
+    provider_status: z.literal("incomplete"),
+    incomplete_reason: z.literal("max_output_tokens"),
+    base_output_ceiling_tokens: z.number().int().positive(),
+    configured_output_headroom_tokens: z.number().int().nonnegative(),
+    effective_max_output_tokens: z.number().int().positive(),
+    input_tokens: NullableTokenCountSchema,
+    cached_input_tokens: NullableTokenCountSchema,
+    output_tokens: NullableTokenCountSchema,
+    reasoning_tokens: NullableTokenCountSchema,
+    non_reasoning_output_tokens: NullableTokenCountSchema,
+    partial_output_chars: z.number().int().nonnegative(),
+    partial_output_sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    provider_model: z.string().min(1),
+    provider_response_id: z.string().min(1).nullable(),
+    provider_request_id: z.string().min(1).nullable(),
+    effective_base_url: z.string().min(1),
+    runtime_logical_call_count: z.literal(1),
+    runtime_incomplete_retry_count: z.literal(0),
+    sdk_max_retries: z.number().int().nonnegative(),
+    actual_adapter_request_count: z.null(),
+    request_count_observability: z.literal("unavailable"),
+})
+    .strict();
+export class ReconstructLlmDispatchFailureError extends Error {
+    unitId;
+    artifactName;
+    callKind;
+    evidence;
+    constructor(args) {
+        super(`reconstruct LLM dispatch failed for ${args.artifactName}: ` +
+            args.evidence.failure_code, { cause: args.cause });
+        this.name = "ReconstructLlmDispatchFailureError";
+        this.unitId = args.unitId;
+        this.artifactName = args.artifactName;
+        this.callKind = args.callKind;
+        this.evidence = args.evidence;
+    }
+}
+export function readReconstructLlmDispatchFailureError(error) {
+    return error instanceof ReconstructLlmDispatchFailureError ? error : null;
+}
+function sha256(value) {
+    return crypto.createHash("sha256").update(value).digest("hex");
+}
+export function createReconstructLlmDispatchFailureArtifact(args) {
+    const failureId = `llm-failure:${sha256([
+        args.sessionId,
+        args.attemptId,
+        args.error.unitId,
+        args.error.artifactName,
+        args.error.callKind,
+        args.error.evidence.provider_response_id ?? "no-response-id",
+    ].join(":")).slice(0, 20)}`;
+    return ReconstructLlmDispatchFailureArtifactSchema.parse({
+        schema_version: RECONSTRUCT_LLM_DISPATCH_FAILURE_SCHEMA_VERSION,
+        failure_id: failureId,
+        session_id: args.sessionId,
+        created_at: args.createdAt ?? new Date().toISOString(),
+        owner_attempt_id: args.attemptId,
+        unit_id: args.error.unitId,
+        artifact_name: args.error.artifactName,
+        call_kind: args.error.callKind,
+        ...args.error.evidence,
+        runtime_logical_call_count: 1,
+        runtime_incomplete_retry_count: 0,
+    });
+}
+function failureFileName(failureId) {
+    if (!/^llm-failure:[a-f0-9]{20}$/.test(failureId)) {
+        throw new Error(`invalid reconstruct LLM dispatch failure id: ${failureId}`);
+    }
+    return `${failureId.replace(/^llm-failure:/, "failure-")}.yaml`;
+}
+export function reconstructLlmDispatchFailurePath(sessionRoot, failureId) {
+    return path.join(path.resolve(sessionRoot), RECONSTRUCT_LLM_DISPATCH_FAILURE_DIR, failureFileName(failureId));
+}
+export function isReconstructLlmDispatchFailureRef(sessionRoot, artifactRef) {
+    const root = path.resolve(sessionRoot, RECONSTRUCT_LLM_DISPATCH_FAILURE_DIR);
+    const resolved = path.resolve(artifactRef);
+    return path.dirname(resolved) === root &&
+        path.basename(resolved).startsWith("failure-") &&
+        path.extname(resolved) === ".yaml";
+}
+export function isReconstructLlmDispatchFailureTempRef(sessionRoot, artifactRef) {
+    const root = path.resolve(sessionRoot, RECONSTRUCT_LLM_DISPATCH_FAILURE_DIR);
+    const resolved = path.resolve(artifactRef);
+    return path.dirname(resolved) === root &&
+        path.basename(resolved).startsWith(".pending-") &&
+        path.extname(resolved) === ".yaml";
+}
+async function fsyncDirectory(dirPath) {
+    const handle = await fs.open(dirPath, fsConstants.O_RDONLY);
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function assertReconstructLlmDispatchFailureDirectory(sessionRoot) {
+    const lexicalRoot = path.resolve(sessionRoot);
+    const rootStat = await fs.lstat(lexicalRoot);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+        throw new Error(`reconstruct session root is not a real directory: ${lexicalRoot}`);
+    }
+    const realRoot = await fs.realpath(lexicalRoot);
+    const dirPath = path.join(lexicalRoot, RECONSTRUCT_LLM_DISPATCH_FAILURE_DIR);
+    let created = false;
+    try {
+        await fs.mkdir(dirPath);
+        created = true;
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    const stat = await fs.lstat(dirPath);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error(`LLM dispatch failure directory is not a real directory: ${dirPath}`);
+    }
+    const realDir = await fs.realpath(dirPath);
+    if (path.dirname(realDir) !== realRoot) {
+        throw new Error(`LLM dispatch failure directory escapes session root: ${realDir}`);
+    }
+    if (created)
+        await fsyncDirectory(lexicalRoot);
+    return dirPath;
+}
+export async function planReconstructLlmDispatchFailureWrite(args) {
+    const artifact = ReconstructLlmDispatchFailureArtifactSchema.parse(args.artifact);
+    const dirPath = await assertReconstructLlmDispatchFailureDirectory(args.sessionRoot);
+    const contents = stringifyYaml(artifact);
+    const contentSha256 = sha256(contents);
+    return {
+        finalRef: path.join(dirPath, failureFileName(artifact.failure_id)),
+        tempRef: path.join(dirPath, `.pending-${contentSha256.slice(0, 16)}-${crypto.randomUUID()}.yaml`),
+        contentSha256,
+    };
+}
+export async function writeReconstructLlmDispatchFailureTemp(args) {
+    const artifact = ReconstructLlmDispatchFailureArtifactSchema.parse(args.artifact);
+    const dirPath = await assertReconstructLlmDispatchFailureDirectory(args.sessionRoot);
+    const contents = stringifyYaml(artifact);
+    const contentSha256 = sha256(contents);
+    const plan = args.plan ?? await planReconstructLlmDispatchFailureWrite(args);
+    if (plan.contentSha256 !== contentSha256 ||
+        plan.finalRef !== path.join(dirPath, failureFileName(artifact.failure_id)) ||
+        !isReconstructLlmDispatchFailureTempRef(args.sessionRoot, plan.tempRef)) {
+        throw new Error("LLM dispatch failure write plan does not match artifact bytes");
+    }
+    const scratchRef = path.join(dirPath, `.scratch-${contentSha256.slice(0, 16)}-${crypto.randomUUID()}.yaml`);
+    const handle = await fs.open(scratchRef, fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY | fsConstants.O_NOFOLLOW, 0o600);
+    try {
+        await handle.writeFile(contents, "utf8");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await fs.rename(scratchRef, plan.tempRef);
+    await fsyncDirectory(dirPath);
+    return plan;
+}
+export async function publishReconstructLlmDispatchFailureTemp(args) {
+    const dirPath = await assertReconstructLlmDispatchFailureDirectory(args.sessionRoot);
+    if (!isReconstructLlmDispatchFailureTempRef(args.sessionRoot, args.tempRef) ||
+        !isReconstructLlmDispatchFailureRef(args.sessionRoot, args.finalRef) ||
+        path.dirname(path.resolve(args.tempRef)) !== dirPath ||
+        path.dirname(path.resolve(args.finalRef)) !== dirPath) {
+        throw new Error("LLM dispatch failure publish refs must stay inside the failure directory");
+    }
+    try {
+        await fs.link(args.tempRef, args.finalRef);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== "EEXIST") {
+            if (code !== "ENOENT")
+                throw error;
+            const finalStat = await fs.lstat(args.finalRef).catch(() => null);
+            if (!finalStat?.isFile() || finalStat.isSymbolicLink())
+                throw error;
+        }
+    }
+    await fs.rm(args.tempRef, { force: true });
+    await fsyncDirectory(dirPath);
+}
+async function readFailureBytesNoFollow(artifactRef) {
+    const handle = await fs.open(artifactRef, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile()) {
+            throw new Error(`LLM dispatch failure artifact is not a regular file: ${artifactRef}`);
+        }
+        return await handle.readFile();
+    }
+    finally {
+        await handle.close();
+    }
+}
+function parseFailureBytes(bytes) {
+    return ReconstructLlmDispatchFailureArtifactSchema.parse(parseYaml(bytes.toString("utf8")));
+}
+export async function readReconstructLlmDispatchFailureArtifactWithHash(args) {
+    await assertReconstructLlmDispatchFailureDirectory(args.sessionRoot);
+    if (!isReconstructLlmDispatchFailureRef(args.sessionRoot, args.artifactRef) &&
+        !(args.allowTemp === true &&
+            isReconstructLlmDispatchFailureTempRef(args.sessionRoot, args.artifactRef))) {
+        throw new Error(`LLM dispatch failure artifact ref escapes failure directory: ${args.artifactRef}`);
+    }
+    const bytes = await readFailureBytesNoFollow(args.artifactRef);
+    return {
+        artifact: parseFailureBytes(bytes),
+        sha256: sha256(bytes),
+    };
+}
+export async function readReconstructLlmDispatchFailureArtifact(artifactRef) {
+    return parseFailureBytes(await readFailureBytesNoFollow(artifactRef));
+}
+export async function sha256ReconstructLlmDispatchFailureArtifact(artifactRef) {
+    return sha256(await readFailureBytesNoFollow(artifactRef));
+}
+export function projectReconstructLlmDispatchFailureSummary(artifact, artifactRef) {
+    return {
+        failure_code: artifact.failure_code,
+        unit_id: artifact.unit_id,
+        artifact_name: artifact.artifact_name,
+        provider_status: artifact.provider_status,
+        incomplete_reason: artifact.incomplete_reason,
+        base_output_ceiling_tokens: artifact.base_output_ceiling_tokens,
+        configured_output_headroom_tokens: artifact.configured_output_headroom_tokens,
+        effective_max_output_tokens: artifact.effective_max_output_tokens,
+        input_tokens: artifact.input_tokens,
+        cached_input_tokens: artifact.cached_input_tokens,
+        output_tokens: artifact.output_tokens,
+        reasoning_tokens: artifact.reasoning_tokens,
+        non_reasoning_output_tokens: artifact.non_reasoning_output_tokens,
+        actual_adapter_request_count: artifact.actual_adapter_request_count,
+        request_count_observability: artifact.request_count_observability,
+        failure_artifact_ref: artifactRef,
+    };
+}

package/dist/core-runtime/reconstruct/llm-touch-fingerprint.js

@@ -0,0 +1,94 @@
+import { createHash } from "node:crypto";
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        return `{${Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+function sha256Text(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+/**
+ * Compute the staged non-circular fingerprint. The parameter types admit ONLY ⓐ + ⓑ — the in-epoch
+ * LLM output (ⓒ) has no slot, so it cannot reach the key by construction (§4.4 non-circular-key).
+ */
+export function llmTouchFingerprint(layer1, preExecution) {
+    const declaredClosure = [
+        // ⓐ
+        "content_sha256",
+        "adapter_version",
+        "value_tile_config",
+        "data_layer_caps",
+        // ⓑ
+        "leaf_reader_model_identity",
+        "execution_adapter",
+        "declared_billing_mode",
+        "reasoning_effort",
+        "leaf_prompt_sha256",
+        "schema_tool_version",
+        "comprehension_version",
+        "structure_leaf_trigger_config",
+        "read_set_logic_sha256",
+    ];
+    const fingerprint_sha256 = sha256Text(stableJson({ layer1_pre_image: layer1, pre_execution_pre_image: preExecution }));
+    return {
+        fingerprint_sha256,
+        declared_llm_touch_dependency_closure: declaredClosure,
+        fingerprint_covers_declared_closure: true,
+        dependency_discovery_realization: "declared_closure_only",
+    };
+}
+/**
+ * In-epoch LLM OUTPUT (ⓒ) field names that must NEVER appear inside a gating reuse key (§11 R3).
+ * If any of these is serialized into a seed digest, an LLM output would gate its own reuse (the
+ * self-gating circularity). The fingerprint VALUE (`epoch_fingerprint_contribution`) is allowed —
+ * it is the ⓐ+ⓑ digest, not ⓒ.
+ */
+export const LLM_TOUCH_IN_EPOCH_OUTPUT_FIELDS = [
+    "spine_claims",
+    "confidence_by_claim",
+    "limiting_witness",
+    "leaf_read_attempt",
+    "tentative_label",
+    // P1-C2-B′ §3: the captured role/note are LLM output too — guard them out of any gating key.
+    "semantic_role",
+    "captured_note",
+    // Layer-2 semantic-map ⓒ fields (wiring design 20260702 §5 F9): the denylist must learn each new
+    // LLM-output vocabulary or a future edit serializing a map/projection instance into a gating key
+    // passes fail-OPEN (the recursive guard only knows enumerated names).
+    "semantic_summary",
+    "semantic_boundaries",
+    "character_before",
+    "character_after",
+    "refuted_disclosure",
+];
+const IN_EPOCH_OUTPUT_SET = new Set(LLM_TOUCH_IN_EPOCH_OUTPUT_FIELDS);
+/**
+ * Runtime non-circular validator (§11 R3): assert that a gating-key input (the object a seed reuse
+ * digest serializes — e.g. the source-observations reuse projection or the authored-artifact reuse
+ * match) contains NO in-epoch LLM output field. Scoped to the REAL seed digests, not just the
+ * fingerprint function (the gate's T3 finding: the type guard only protects llmTouchFingerprint).
+ * Throws on the first ⓒ key found so the leak fails closed at construction time.
+ */
+export function assertGatingKeyExcludesInEpochOutput(label, gatingKeyInput) {
+    const visit = (node, path) => {
+        if (Array.isArray(node)) {
+            node.forEach((item, i) => visit(item, `${path}[${i}]`));
+            return;
+        }
+        if (node && typeof node === "object") {
+            for (const key of Object.keys(node)) {
+                if (IN_EPOCH_OUTPUT_SET.has(key)) {
+                    throw new Error(`${label}: gating reuse key must not contain in-epoch LLM output field '${key}' at ${path}.${key} (§11 R3 non-circular-key: an LLM output would gate its own reuse). Fold the llm_touch_fingerprint VALUE instead of the comprehension-artifact instance.`);
+                }
+                visit(node[key], `${path}.${key}`);
+            }
+        }
+    };
+    visit(gatingKeyInput, label);
+}

package/dist/core-runtime/reconstruct/material-admission-validation.js

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { atomicWriteYamlDocument as writeYamlDocument } from "../artifact-io.js";
+import { assertObligation } from "./obligation-assertion.js";
 const ADMISSION_PHASES = [
     "pre_seed_purpose_element",
     "pre_seed_material_value",
@@ -264,6 +265,22 @@ export function validateMaterialAdmissionLedger(args) {
     const seen = new Set();
     let requiredOrAdmittedRowCount = 0;
     let downstreamConsumedRowCount = 0;
+    // G(a) obligation recorder (INV-OBLIGATION-COVERAGE-1). Placed before the per-row loop so the
+    // unconditional row-rule enforcers (uniqueness / consumer-closure / diagnostic-actionability /
+    // rejected-replay) record on zero-row input too. The two reference-integrity obligations are
+    // gated on their authoritative input being present, since the validator skips them otherwise
+    // (control never reaches the enforcer when the selected frame / observed source refs are absent).
+    const assertedObligationIds = [];
+    assertObligation(assertedObligationIds, "validate_admission_row_uniqueness");
+    assertObligation(assertedObligationIds, "require_admitted_required_or_supporting_rows_to_have_candidate_seed_maturation_limitation_blocked_or_out_of_scope_consumer");
+    assertObligation(assertedObligationIds, "prevent_diagnostic_or_trace_only_rows_from_silently_affecting_actionability");
+    assertObligation(assertedObligationIds, "require_rejected_ambiguous_rows_to_preserve_replayable_evidence_or_limitation");
+    if (purposeElements.size > 0) {
+        assertObligation(assertedObligationIds, "validate_purpose_element_refs_against_selected_purpose_frame");
+    }
+    if (knownSourceRefs.size > 0) {
+        assertObligation(assertedObligationIds, "validate_source_refs_against_observed_source_refs");
+    }
     for (const [index, row] of ledger.admission_rows.entries()) {
         const subject = row.admission_id || `admission_rows[${index}]`;
         if (!row.admission_id) {
@@ -461,6 +478,7 @@ export function validateMaterialAdmissionLedger(args) {
         validation_results: violations.length === 0
             ? ["material_admission_valid"]
             : ["material_admission_invalid"],
+        asserted_obligation_ids: assertedObligationIds,
         violations,
     };
 }

package/dist/core-runtime/reconstruct/material-profile-validation.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { atomicWriteYamlDocument as writeYamlDocument, assertArrayField } from "../artifact-io.js";
 import { isTargetMaterialKind, } from "../target-material-kind.js";
+import { assertObligation } from "./obligation-assertion.js";
 import { loadReconstructContractRegistry, resolveRegistryRef, } from "./contract-registry.js";
 function isoNow() {
     return new Date().toISOString();
@@ -58,6 +59,18 @@ export function validateTargetMaterialProfile(args) {
     assertArrayField(args.targetMaterialProfile.detection?.per_ref, "target-material-profile", "detection.per_ref");
     const profile = args.targetMaterialProfile;
     const violations = [];
+    // G(a) deferred-7 slice 2: record the two obligations this validator fully enforces over every selected
+    // source profile. Stamped before the per-profile loop so they fire on zero selected profiles. The
+    // validation artifact is reuse-hashed (run.ts target_material_profile_validation_sha256) AND
+    // scout-captured — asserted_obligation_ids is in-memory-only (Stage 0 #145), so stamping it does not
+    // rotate reuse. PARKED (see obligation-coverage-ledger.yaml): the four mixed_targets_/partial_composite_
+    // obligations — member→aggregate purpose mapping and partial-member ready-projection limiting are
+    // NOT_FOUND (no field, no check), and the two per-member preservation obligations are PARTIAL (the
+    // field-match runs for ALL selected profiles, not the named mixed scope, and names facets absent from
+    // the schema: support_state / source_refs).
+    const assertedObligationIds = [];
+    assertObligation(assertedObligationIds, "every_selected_source_profile_snapshot_contains_version_policy_required_fields");
+    assertObligation(assertedObligationIds, "every_selected_source_profile_snapshot_matches_source_profile_records_by_profile_id_and_target_material_kind");
     const projectRoot = projectRootFromRegistryPath(args.registryRef);
     if (!isTargetMaterialKind(profile.target_material_kind)) {
         violations.push(violation({
@@ -186,6 +199,7 @@ export function validateTargetMaterialProfile(args) {
         validation_results: violations.length === 0
             ? ["target_material_profile_valid"]
             : ["target_material_profile_invalid"],
+        asserted_obligation_ids: assertedObligationIds,
         violations,
     };
 }