feat(confidence-engine): add saveFocusedInvestigationEvidence persistence operation (Experiment 8)

Add exported saveFocusedInvestigationEvidence(checkpoint, identity, metadata,
outputPath) to the canonical experiment helper. Validates output path, exactly
one valid deconstruction contribution, required identity fields, and exact input
values. Writes formatted JSON, reads back, verifies deep structural equality.
Rejects ambiguous checkpoints instead of silently selecting a contribution.

Deterministic test covers: positive file write, structured evidence completeness,
input fidelity, identity fidelity, return values, missing path rejection, missing
contribution rejection, ambiguous contribution rejection. All OS temp files cleaned
in finally blocks.

Zero live model calls. Zero browser calls. No production code modified.
This commit is contained in:
2026-10-09 14:33:33 +01:00
parent aa57d8589c
commit 0698a1a61e
4 changed files with 273 additions and 2 deletions
+95 -1
View File
@@ -583,4 +583,98 @@ function serializeFocusedInvestigationEvidence(checkpoint, identity, metadata) {
};
}
module.exports = { runLiveExperiment, extractLiveExperimentCheckpoint, _extractReasoningState, composeDeepInvestigationCheckpoint, serializeFocusedInvestigationEvidence };
/**
* Save a completed focused-investigation checkpoint to a durable JSON file.
*
* Wrapper around `serializeFocusedInvestigationEvidence()` that performs
* explicit persistence via the caller-supplied output path. Intended for
* deterministic test fixtures and future live experiment runbooks — NOT
* called automatically from production code.
*
* @param {object} checkpoint — returned from composeDeepInvestigationCheckpoint()
* @param {object} identity — { experimentId, scenarioId, targetNodeId, evidenceDesignation }
* @param {object} metadata — { modelName?, providerGenerateCalls?, modelElapsedMs?, endToEndElapsedMs?, success? }
* @param {string} outputPath — explicit absolute or relative file path for the JSON output
* @returns {{ output_path: string, verifiedEvidence: object }} { output_path, verifiedEvidence }
* @throws {Error} on invalid inputs, missing required fields, ambiguous contribution, or I/O failure
*/
function saveFocusedInvestigationEvidence(checkpoint, identity, metadata, outputPath) {
const fs = require("fs");
/* ── 2. Require explicit non-empty output path ────────────────────── */
if (!outputPath || typeof outputPath !== "string" || !outputPath.trim()) {
throw new Error("saveFocusedInvestigationEvidence requires an explicit non-empty outputPath string");
}
/* ── 3. Validate checkpoint has exactly one valid contribution ────── */
const contributions = Array.isArray(checkpoint?.postEpisodeContributions)
? checkpoint.postEpisodeContributions
: [];
const validContributionCandidates = contributions.filter(
(c) => Array.isArray(c?.observations) && Array.isArray(c?.uncertainties)
);
if (validContributionCandidates.length === 0) {
throw new Error(
"saveFocusedInvestigationEvidence requires a checkpoint with at least one valid focused-deconstruction contribution; found 0"
);
}
if (validContributionCandidates.length > 1) {
throw new Error(
"saveFocusedInvestigationEvidence rejects ambiguous checkpoint: multiple candidates exist (" +
validContributionCandidates.length +
"); supply a single-target checkpoint or resolve ambiguity before saving"
);
}
/* ── 4. Validate identity and input values ────────────────────────── */
if (!identity || typeof identity !== "object") {
throw new Error("saveFocusedInvestigationEvidence requires an identity object");
}
if (identity.experimentId == null) {
throw new Error("saveFocusedInvestigationEvidence: identity.missing experimentId");
}
if (identity.scenarioId == null) {
throw new Error("saveFocusedInvestigationEvidence: identity.missing scenarioId");
}
if (identity.targetNodeId == null) {
throw new Error("saveFocusedInvestigationEvidence: identity.missing targetNodeId");
}
if (identity.evidenceDesignation == null) {
throw new Error("saveFocusedInvestigationEvidence: identity.missing evidenceDesignation");
}
const fiInputs = checkpoint.focusedInvestigationInput;
if (!fiInputs || typeof fiInputs !== "object") {
throw new Error("saveFocusedInvestigationEvidence: checkpoint missing focusedInvestigationInput object");
}
if (fiInputs.targetDescription == null || fiInputs.question == null || fiInputs.answer == null) {
throw new Error(
"saveFocusedInvestigationEvidence: checkpoint missing required focused-investigation input values (targetDescription, question, answer)"
);
}
/* ── 1. Serialize via existing serializer ─────────────────────────── */
const serialized = serializeFocusedInvestigationEvidence(checkpoint, identity, metadata);
/* ── 5-6. Write the complete record as readable JSON ──────────────── */
const jsonContent = JSON.stringify(serialized, null, 2);
fs.writeFileSync(outputPath, jsonContent, "utf8");
/* ── 7-8. Read back and verify structural equality ────────────────── */
const recoveredRaw = fs.readFileSync(outputPath, "utf8");
const recovered = JSON.parse(recoveredRaw);
if (JSON.stringify(serialized) !== JSON.stringify(recovered)) {
throw new Error(
"saveFocusedInvestigationEvidence: write/read-back verification failed — recovered JSON does not match serialized record"
);
}
/* ── 9. Return output path and verified evidence record ───────────── */
return { output_path: outputPath, verifiedEvidence: recovered };
}
module.exports = { runLiveExperiment, extractLiveExperimentCheckpoint, _extractReasoningState, composeDeepInvestigationCheckpoint, serializeFocusedInvestigationEvidence, saveFocusedInvestigationEvidence };