test(confidence-engine): expose reconstruction experiment seam

scripts/start-case-experiment-helper.cjs

@@ -51,13 +51,19 @@ function readScenarioInput(argv) {
   return { scenario: argv.slice(startIdx).join(" ") };
 }
 
-async function runStartCaseExperiment(scenarioInput) {
-  // Deterministic mode: skip environment checks and use inline test double.
-  // Controlled via START_CASE_EXPERIMENT_HELPER_MOCK=1 for standalone apparatus tests.
-  const isMock = process.env.START_CASE_EXPERIMENT_HELPER_MOCK === "1";
+async function runStartCaseExperiment(scenarioInput, experimentInstruction) {
+  // ── Experiment seam bridge: supply instruction to production path ──
+  const hadEnvVar = process.env.RECONSTRUCTION_EXPERIMENT_INSTRUCTION != null;
+  const previousEnvValue = process.env.RECONSTRUCTION_EXPERIMENT_INSTRUCTION;
+  if (experimentInstruction) {
+    process.env.RECONSTRUCTION_EXPERIMENT_INSTRUCTION = experimentInstruction;
+  }
 
   let startCase;
+  const isMock = process.env.START_CASE_EXPERIMENT_HELPER_MOCK === "1";
+
   if (isMock) {
+    // Deterministic mode: skip environment checks and use inline test double.
     startCase = async (body) => {
       // Deterministic inline test double — no live model calls.
       const shouldFail = process.env.START_CASE_EXPERIMENT_HELPER_FORCE_FAIL === "1";
@@ -88,9 +94,26 @@ async function runStartCaseExperiment(scenarioInput) {
     startCase = _sc;
   }
 
+  let result;
   const endToEndStartedAt = Date.now();
-  const result = await startCase(scenarioInput);
-  const endToEndElapsedMs = Date.now() - endToEndStartedAt;
+  try {
+    result = await startCase(scenarioInput);
+  } finally {
+    // Clean up experiment env var after execution regardless of outcome
+    if (experimentInstruction && !hadEnvVar) {
+      delete process.env.RECONSTRUCTION_EXPERIMENT_INSTRUCTION;
+    } else if (!hadEnvVar) {
+      // was not set before and not set during — ensure it stays unset
+      delete process.env.RECONSTRUCTION_EXPERIMENT_INSTRUCTION;
+    } else if (!experimentInstruction && hadEnvVar) {
+      // restore original value that existed before
+      if (previousEnvValue === undefined) {
+        delete process.env.RECONSTRUCTION_EXPERIMENT_INSTRUCTION;
+      } else {
+        process.env.RECONSTRUCTION_EXPERIMENT_INSTRUCTION = previousEnvValue;
+      }
+    }
+  }
 
   return {
     success: result.success,
@@ -100,7 +123,7 @@ async function runStartCaseExperiment(scenarioInput) {
     selectedQuestion: result.selectedQuestion?.question ?? null,
     assessmentPhase: result.assessment?.phase ?? null,
     assessmentProgress: result.assessment?.progress ?? null,
-    endToEndElapsedMs,
+    endToEndElapsedMs: Date.now() - endToEndStartedAt,
     diagnostics: result.diagnostics ?? null,
     error: result.success ? null : (result.error ?? "unknown"),
     statusCode: result.statusCode ?? (result.success ? 200 : 500),
@@ -137,8 +160,15 @@ async function runStartCaseExperiment(scenarioInput) {
   }
 
   try {
+    // ── Experiment seam: parse optional experiment instruction ──
+    const experimentIdx = process.argv.indexOf("--experiment-instruction");
+    let experimentInstruction = null;
+    if (experimentIdx !== -1 && experimentIdx + 1 < process.argv.length) {
+      experimentInstruction = process.argv[experimentIdx + 1];
+    }
+
     const scenarioInput = readScenarioInput(process.argv);
-    const result = await runStartCaseExperiment(scenarioInput);
+    const result = await runStartCaseExperiment(scenarioInput, experimentInstruction);
 
     console.log(JSON.stringify(result, null, 2));
     process.exit(result.success ? 0 : 1);