@zergai/ztc 0.4.0-beta.1 → 0.5.0-beta.1

package/dist/optimize/adapters/types.d.ts

@@ -1,6 +1,7 @@
 import type { ShellResult } from '../../agent/commands/types.js';
 import type { OptimizationEngineId, OptimizationPlanArtifacts, OptimizationSpec } from '../types.js';
 import type { OptimizationStrategyVariant } from '../arl.js';
+import type { OptimizationMeasurementSource, OptimizationMeasurementReport } from '../measurements.js';
 export interface OptimizationBranchVariant {
     id: string;
     label: string;
@@ -80,6 +81,8 @@ export interface OptimizationExecutionResult {
     deferredStages: OptimizationEngineId[];
     notes: string[];
     metrics?: OptimizationExecutionMetrics;
+    measurement?: OptimizationMeasurementSource;
+    measurementReport?: OptimizationMeasurementReport;
 }
 export interface OptimizationAdapter {
     readonly id: string;

package/dist/optimize/adapters/zergpod.js

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'fs';
 import { basename, dirname, join, resolve } from 'path';
+import { captureAdapterOptimizationMeasurement } from '../measurements.js';
 import { run_shell_with_timeout, shell_join, sh_quote } from './runtime.js';
 import { resolve_path_reference, resolve_path_within_cwd } from '../paths.js';
 function repo_root() {
@@ -428,9 +429,11 @@ async function evaluate_candidate_spec(spec, deps, artifacts) {
             improved: Boolean(payload.improved),
         },
     };
-    write_json_atomic(join(artifacts.runDir, 'execution_result.json'), result);
+    const capturedResult = captureAdapterOptimizationMeasurement(result, adapterPayloadPath, readFileSync(adapterPayloadPath, 'utf-8'), !shellResult.truncated, { runId: artifacts.runId, unit: 'hours', selection: { projectDir, benchName,
+            baselineRuntimeHours: payload.baseline_projected_runtime_hours, baselineRunId: payload.baseline_run_id, profile: spec.profile } });
+    write_json_atomic(join(artifacts.runDir, 'execution_result.json'), capturedResult);
     deps.onProgress?.(`ZergPod bench: ${payload.candidate_variant_id} completed with candidate_value=${payload.candidate_projected_runtime_hours.toFixed(4)} baseline_value=${payload.baseline_projected_runtime_hours.toFixed(4)} improved=${payload.improved}.`);
-    return result;
+    return capturedResult;
 }
 export const zergpodOptimizationAdapter = {
     id: 'zergpod_audio',

package/dist/optimize/baseline.js

@@ -1,8 +1,10 @@
+import { evaluate_optimization_adapter } from './adapters/index.js';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { basename, extname, join } from 'path';
 import { extract_code_payload, generate_text_with_backend } from './llm.js';
 import { resolve_path_reference, resolve_path_within_cwd } from './paths.js';
 import { is_better_result } from './results.js';
+import { assessOptimizationResult } from './measurements.js';
 function build_sub_artifacts(parent, subdir) {
     const runDir = join(parent.runDir, subdir);
     mkdirSync(runDir, { recursive: true });
@@ -86,18 +88,10 @@ function json_artifact_requirements(spec, adapter) {
     ];
 }
 function needs_baseline_generation(currentResult) {
-    if (!currentResult.ok) {
-        return true;
-    }
-    const kind = currentResult.metrics?.objectiveKind || 'unknown';
-    const value = currentResult.metrics?.candidateValue;
-    if (value === undefined) {
-        return true;
-    }
-    if (kind === 'score' || kind === 'correctness' || kind === 'pass_rate') {
-        return value < 1.0;
-    }
-    return false;
+    const reported = assessOptimizationResult(currentResult);
+    // No generic scalar threshold proves correctness. Unknown data receives the bounded generation budget.
+    return reported.compatibility !== 'compatible' || reported.objectiveKind === 'score'
+        || reported.objectiveKind === 'correctness' || reported.objectiveKind === 'pass_rate';
 }
 function build_baseline_prompt(spec, adapter, seedPath, seedSource, attempt, previousFailures) {
     const modeContext = load_mode_context(spec);
@@ -150,20 +144,20 @@ export async function execute_native_baseline(spec, adapter, deps, artifacts) {
     if (!adapter.evaluate) {
         return {
             spec,
-            result: await adapter.execute(spec, deps, artifacts),
+            result: await evaluate_optimization_adapter(adapter, spec, deps, artifacts),
             notes: ['Native baseline fell back to adapter.execute because candidate-level evaluation is unavailable.'],
         };
     }
     if (!spec.target || (spec.target.kind !== 'file' && spec.target.kind !== 'artifact')) {
         return {
             spec,
-            result: await adapter.evaluate(spec, deps, artifacts),
+            result: await evaluate_optimization_adapter(adapter, spec, deps, artifacts),
             notes: ['Native baseline evaluated the current spec directly because no concrete artifact target was provided.'],
         };
     }
     const seedPath = resolve_target_path(spec);
     const seedSource = readFileSync(seedPath, 'utf-8');
-    const currentResult = await adapter.evaluate(spec, deps, artifacts);
+    const currentResult = await evaluate_optimization_adapter(adapter, spec, deps, artifacts);
     deps.onProgress?.(`Baseline: seed evaluation finished with candidate_value=${currentResult.metrics?.candidateValue ?? 'n/a'} status=${currentResult.status}.`);
     if (!needs_baseline_generation(currentResult)) {
         return {
@@ -209,7 +203,7 @@ export async function execute_native_baseline(spec, adapter, deps, artifacts) {
         writeFileSync(candidateArtifacts.specPath, JSON.stringify(candidateSpec, null, 2), 'utf-8');
         writeFileSync(candidateArtifacts.planPath, '', 'utf-8');
         deps.onProgress?.(`Baseline: evaluating candidate ${attempt}/${baseline_candidate_count(spec)} at ${candidatePath}.`);
-        const candidateResult = await adapter.evaluate(candidateSpec, deps, candidateArtifacts);
+        const candidateResult = await evaluate_optimization_adapter(adapter, candidateSpec, deps, candidateArtifacts);
         deps.onProgress?.(`Baseline: candidate ${attempt}/${baseline_candidate_count(spec)} finished with candidate_value=${candidateResult.metrics?.candidateValue ?? 'n/a'} status=${candidateResult.status}.`);
         summaries.push({
             attempt,
@@ -221,11 +215,6 @@ export async function execute_native_baseline(spec, adapter, deps, artifacts) {
             bestSpec = candidateSpec;
             bestResult = candidateResult;
         }
-        const objectiveKind = candidateResult.metrics?.objectiveKind;
-        const candidateValue = candidateResult.metrics?.candidateValue;
-        if ((objectiveKind === 'score' || objectiveKind === 'correctness' || objectiveKind === 'pass_rate') && candidateValue !== undefined && candidateValue >= 1.0) {
-            break;
-        }
     }
     writeFileSync(join(candidateDir, 'candidate_results.json'), JSON.stringify(summaries, null, 2), 'utf-8');
     return {

package/dist/optimize/branch.js

@@ -1,7 +1,9 @@
+import { evaluate_optimization_adapter } from './adapters/index.js';
 import { mkdirSync, writeFileSync } from 'fs';
 import { extname, join } from 'path';
 import { execute_native_combine } from './combine.js';
-import { is_better_result } from './results.js';
+import { is_better_result, result_score } from './results.js';
+import { compareOptimizationResults } from './measurements.js';
 import { execute_native_tge } from './tge.js';
 import { resolve_path_reference, resolve_path_within_cwd } from './paths.js';
 function positive_int_env(name) {
@@ -56,12 +58,6 @@ function branch_family_key(record) {
     }
     return 'branch';
 }
-function branch_record_score(record) {
-    const result = record.result || null;
-    const metrics = result?.metrics || null;
-    const candidateValue = metrics?.candidateValue;
-    return typeof candidateValue === 'number' && Number.isFinite(candidateValue) ? candidateValue : Number.NEGATIVE_INFINITY;
-}
 function build_sub_artifacts(parent, subdir) {
     const runDir = join(parent.runDir, subdir);
     mkdirSync(runDir, { recursive: true });
@@ -100,9 +96,7 @@ async function materialize_branch_seed(spec, adapter, deps, currentResult, artif
         writeFileSync(artifacts.requestPath, branchSpec.request || '', 'utf-8');
         writeFileSync(artifacts.specPath, JSON.stringify(branchSpec, null, 2), 'utf-8');
         writeFileSync(artifacts.planPath, '', 'utf-8');
-        const branchResult = adapter.evaluate
-            ? await adapter.evaluate(branchSpec, deps, artifacts)
-            : await adapter.execute(branchSpec, deps, artifacts);
+        const branchResult = await evaluate_optimization_adapter(adapter, branchSpec, deps, artifacts);
         return {
             spec: branchSpec,
             result: branchResult,
@@ -178,7 +172,10 @@ export async function execute_native_branch(spec, adapter, deps, artifacts, curr
     }
     const survivorLimit = branch_survivors_per_family(spec);
     const familyRanks = new Map();
-    for (const record of [...branchRecords].sort((left, right) => branch_record_score(right) - branch_record_score(left))) {
+    const comparableRecords = branchRecords.filter(record => compareOptimizationResults(currentResult, record.result).compatibility === 'compatible');
+    for (const record of branchRecords)
+        record.survivedFamilyPolicy = false;
+    for (const record of comparableRecords.sort((left, right) => result_score(right.result) - result_score(left.result))) {
         const familyKey = branch_family_key(record);
         const nextRank = (familyRanks.get(familyKey) || 0) + 1;
         familyRanks.set(familyKey, nextRank);
@@ -208,7 +205,7 @@ export async function execute_native_branch(spec, adapter, deps, artifacts, curr
         notes: [
             `Native branch evaluated ${variants.length} branch variant(s).`,
             `Native branch survivor policy preserved top ${survivorLimit} candidate(s) per family across ${familyRanks.size} family/families.`,
-            `Native branch selected ${bestSpec.target?.ref || resolve_target_path(spec)} as the best downstream result.`,
+            `Native branch retained ${bestSpec.target?.ref || resolve_target_path(spec)} after comparing declared reported objectives; verification and benchmark eligibility remain unknown.`,
             ...(bestSpec.target?.ref === spec.target.ref ? ['Native branch kept the incoming candidate; no branch beat the parent result.'] : []),
             ...notes,
         ],

package/dist/optimize/combine.js

@@ -1,3 +1,4 @@
+import { evaluate_optimization_adapter } from './adapters/index.js';
 import { mkdirSync, writeFileSync } from 'fs';
 import { extname, join } from 'path';
 import { is_better_result } from './results.js';
@@ -65,9 +66,7 @@ async function materialize_combine_seed(spec, adapter, deps, currentResult, arti
         writeFileSync(artifacts.requestPath, combineSpec.request || '', 'utf-8');
         writeFileSync(artifacts.specPath, JSON.stringify(combineSpec, null, 2), 'utf-8');
         writeFileSync(artifacts.planPath, '', 'utf-8');
-        const combineResult = adapter.evaluate
-            ? await adapter.evaluate(combineSpec, deps, artifacts)
-            : await adapter.execute(combineSpec, deps, artifacts);
+        const combineResult = await evaluate_optimization_adapter(adapter, combineSpec, deps, artifacts);
         return {
             spec: combineSpec,
             result: combineResult,

package/dist/optimize/executor.js

@@ -1,3 +1,4 @@
+import { evaluate_optimization_adapter } from './adapters/index.js';
 import { copyFileSync, existsSync, mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { resolve_optimization_adapter } from './adapters/index.js';
@@ -6,6 +7,7 @@ import { execute_native_baseline } from './baseline.js';
 import { execute_native_branch } from './branch.js';
 import { materialize_mpe_candidates, promote_mpe_candidate } from './mpe.js';
 import { is_better_result, result_score } from './results.js';
+import { assessOptimizationResult, compareOptimizationResults, describeOptimizationResult } from './measurements.js';
 import { execute_native_tge } from './tge.js';
 function emit_progress(deps, message) {
     deps.onProgress?.(message);
@@ -24,19 +26,6 @@ function materialize_artifacts(parent, subdir) {
         planPath: join(runDir, 'plan.md'),
     };
 }
-function choose_better_result(currentBest, currentCandidate, next, nextCandidate) {
-    if (is_better_result(currentBest, next)) {
-        return true;
-    }
-    const currentScore = currentBest ? result_score(currentBest) : null;
-    const nextScore = result_score(next);
-    if (currentScore === nextScore && currentScore === null) {
-        return currentCandidate === null || currentCandidate.kind !== 'mutated'
-            ? false
-            : nextCandidate.kind === 'base';
-    }
-    return false;
-}
 async function run_native_pipeline(spec, deps, artifacts) {
     const pipelineResult = await run_native_pipeline_stages(spec, deps, artifacts, spec.pipeline, null);
     const currentSpec = pipelineResult.spec;
@@ -66,7 +55,7 @@ async function run_native_pipeline_stages(spec, deps, artifacts, stages, initial
     if (!adapter.evaluate) {
         return {
             spec,
-            result: await adapter.execute(spec, deps, artifacts),
+            result: await evaluate_optimization_adapter(adapter, spec, deps, artifacts),
             stageHistory: [],
             notes: [],
         };
@@ -121,7 +110,7 @@ async function run_native_pipeline_stages(spec, deps, artifacts, stages, initial
         if (stage.engine === 'branch') {
             if (!currentResult) {
                 emit_progress(deps, 'No current result for branch; evaluating the incoming target first.');
-                currentResult = await adapter.evaluate(currentSpec, deps, artifacts);
+                currentResult = await evaluate_optimization_adapter(adapter, currentSpec, deps, artifacts);
                 stageHistory.push({ stage: 'baseline(auto)', runDir: artifacts.runDir, result: currentResult });
             }
             const stageArtifacts = materialize_artifacts(artifacts, stage.engine);
@@ -170,7 +159,7 @@ async function run_native_pipeline_stages(spec, deps, artifacts, stages, initial
         if (stage.engine === 'tge') {
             if (!currentResult) {
                 emit_progress(deps, 'No current result for TGE; evaluating the incoming target first.');
-                currentResult = await adapter.evaluate(currentSpec, deps, stageArtifacts);
+                currentResult = await evaluate_optimization_adapter(adapter, currentSpec, deps, stageArtifacts);
                 stageHistory.push({ stage: 'baseline(auto)', runDir: stageArtifacts.runDir, result: currentResult });
             }
             const stageResult = await execute_native_tge(currentSpec, adapter, deps, stageArtifacts, currentResult);
@@ -184,7 +173,7 @@ async function run_native_pipeline_stages(spec, deps, artifacts, stages, initial
         if (stage.engine === 'arl') {
             if (!currentResult) {
                 emit_progress(deps, 'No current result for ARL; evaluating the incoming target first.');
-                currentResult = await adapter.evaluate(currentSpec, deps, stageArtifacts);
+                currentResult = await evaluate_optimization_adapter(adapter, currentSpec, deps, stageArtifacts);
                 stageHistory.push({ stage: 'baseline(auto)', runDir: stageArtifacts.runDir, result: currentResult });
             }
             const stageResult = await execute_native_arl(currentSpec, adapter, deps, stageArtifacts, currentResult);
@@ -197,7 +186,7 @@ async function run_native_pipeline_stages(spec, deps, artifacts, stages, initial
         }
     }
     if (!currentResult) {
-        currentResult = await adapter.evaluate(currentSpec, deps, artifacts);
+        currentResult = await evaluate_optimization_adapter(adapter, currentSpec, deps, artifacts);
     }
     return {
         spec: currentSpec,
@@ -243,19 +232,19 @@ export async function execute_optimization_spec(spec, deps, artifacts) {
             ? await run_native_pipeline(executionSpec, deps, artifacts)
             : {
                 spec: executionSpec,
-                result: await adapter.execute(executionSpec, deps, artifacts),
+                result: await evaluate_optimization_adapter(adapter, executionSpec, deps, artifacts),
             };
         const result = nativeResult.result;
         result.notes = [...materialized.notes, ...result.notes];
         if (materialized.saveModeAs
-            && result.metrics?.improved
+            && assessOptimizationResult(result).improved === true
             && materialized.candidates[0]
             && materialized.candidates[0].kind === 'mutated') {
             const savedPath = promote_mpe_candidate(materialized.candidates[0], materialized.saveModeAs);
-            result.notes.push(`Saved evolved mode for reuse at ${savedPath}.`);
+            result.notes.push(`Saved evolved mode for reuse at ${savedPath} using reported measurements; verification and benchmark eligibility remain unknown.`);
         }
         else if (materialized.saveModeAs) {
-            result.notes.push(`Skipped saving evolved mode "${materialized.saveModeAs}" because no mutated MPE policy won with a measured downstream improvement.`);
+            result.notes.push(`Skipped saving evolved mode "${materialized.saveModeAs}" because no mutated MPE policy won with a comparable reported downstream improvement.`);
         }
         writeFileSync(executionSpecPath, JSON.stringify(nativeResult.spec, null, 2), 'utf-8');
         writeFileSync(join(artifacts.runDir, 'execution_result.json'), JSON.stringify(result, null, 2), 'utf-8');
@@ -266,7 +255,7 @@ export async function execute_optimization_spec(spec, deps, artifacts) {
     let bestCandidate = null;
     let bestCandidateIndex = 0;
     let bestExecutionSpec = null;
-    let baseCandidateScore = null;
+    let baseResult = null;
     for (const candidate of materialized.candidates) {
         const candidateArtifacts = materialize_artifacts(artifacts, join('mpe_candidates', candidate.kind === 'base' ? 'base' : `candidate_${String(candidate.index).padStart(2, '0')}`));
         writeFileSync(candidateArtifacts.requestPath, candidate.spec.request || '', 'utf-8');
@@ -276,7 +265,7 @@ export async function execute_optimization_spec(spec, deps, artifacts) {
             ? await run_native_pipeline(candidate.spec, deps, candidateArtifacts)
             : {
                 spec: candidate.spec,
-                result: await adapter.execute(candidate.spec, deps, candidateArtifacts),
+                result: await evaluate_optimization_adapter(adapter, candidate.spec, deps, candidateArtifacts),
             };
         const candidateResult = nativeResult.result;
         candidateResult.notes = [
@@ -293,9 +282,11 @@ export async function execute_optimization_spec(spec, deps, artifacts) {
             result: candidateResult,
         });
         if (candidate.kind === 'base') {
-            baseCandidateScore = result_score(candidateResult);
+            baseResult = candidateResult;
         }
-        if (choose_better_result(bestResult, bestCandidate, candidateResult, candidate)) {
+        const comparison = bestResult ? compareOptimizationResults(bestResult, candidateResult) : null;
+        candidateSummaries[candidateSummaries.length - 1].comparison = comparison;
+        if (bestResult === null || is_better_result(bestResult, candidateResult)) {
             bestResult = candidateResult;
             bestCandidate = candidate;
             bestCandidateIndex = candidate.index;
@@ -329,37 +320,31 @@ export async function execute_optimization_spec(spec, deps, artifacts) {
     result.planPath = artifacts.planPath;
     result.specPath = artifacts.specPath;
     writeFileSync(executionSpecPath, JSON.stringify(bestExecutionSpec || selectedCandidate.spec, null, 2), 'utf-8');
+    const hasComparableScore = result_score(result) !== null;
     result.summary = result.ok
-        ? `${result.summary} Selected MPE candidate: ${selectedCandidate.label}.`
+        ? hasComparableScore ? `${result.summary} Selected MPE candidate from comparable reported data: ${selectedCandidate.label}.`
+            : `${result.summary} Retained incoming MPE policy; measurement comparability is unknown.`
         : result.summary;
     result.notes = [
         ...materialized.notes,
-        `Selected MPE candidate ${selectedCandidate.label} from ${materialized.candidates.length} candidate(s).`,
+        hasComparableScore ? `Selected MPE candidate ${selectedCandidate.label} from comparable reported data; verification and benchmark eligibility remain unknown.`
+            : `Retained MPE candidate ${selectedCandidate.label}; no comparable reported winner was established across ${materialized.candidates.length} execution(s).`,
         ...result.notes,
     ];
-    const selectedCandidateScore = result_score(result);
-    if (selectedCandidate.kind === 'mutated'
-        && baseCandidateScore !== null
-        && selectedCandidateScore !== null
-        && selectedCandidateScore > baseCandidateScore) {
-        result.metrics = {
-            objectiveKind: result.metrics?.objectiveKind || spec.objective?.kind || 'score',
-            direction: result.metrics?.direction || 'maximize',
-            ...result.metrics,
-            baselineValue: baseCandidateScore,
-            candidateValue: result.metrics?.candidateValue ?? selectedCandidateScore,
-            deltaValue: selectedCandidateScore - baseCandidateScore,
-            improved: true,
-        };
-        result.notes.push(`Selected mutated MPE candidate improved benchmark score from ${baseCandidateScore} to ${selectedCandidateScore}.`);
+    const reportedImprovement = selectedCandidate.kind === 'mutated' && baseResult !== null && is_better_result(baseResult, result);
+    if (reportedImprovement && baseResult) {
+        const baseline = assessOptimizationResult(baseResult), selected = assessOptimizationResult(result);
+        result.metrics = { ...result.metrics, objectiveKind: selected.objectiveKind, direction: selected.direction,
+            baselineValue: baseline.value, candidateValue: selected.value, deltaValue: selected.value - baseline.value, improved: true };
+        result.notes.push(`Selected mutated MPE candidate improved its comparable reported objective from ${baseline.value} to ${selected.value}; verification and benchmark eligibility remain unknown.`);
     }
     if (materialized.saveModeAs) {
-        if (result.metrics?.improved && selectedCandidate.kind === 'mutated') {
+        if (reportedImprovement) {
             const savedPath = promote_mpe_candidate(selectedCandidate, materialized.saveModeAs);
-            result.notes.push(`Saved evolved mode for reuse at ${savedPath}.`);
+            result.notes.push(`Saved evolved mode for reuse at ${savedPath} using reported measurements; verification and benchmark eligibility remain unknown.`);
         }
         else {
-            result.notes.push(`Skipped saving evolved mode "${materialized.saveModeAs}" because no mutated MPE policy won with a measured downstream improvement.`);
+            result.notes.push(`Skipped saving evolved mode "${materialized.saveModeAs}" because no mutated MPE policy won with a comparable reported downstream improvement.`);
         }
     }
     if (bestResult?.stdoutPath) {
@@ -376,6 +361,7 @@ export async function execute_optimization_spec(spec, deps, artifacts) {
             copyFileSync(selectedPlanJsonPath, join(artifacts.runDir, 'execution_plan.json'));
         }
     }
-    writeFileSync(join(artifacts.runDir, 'execution_result.json'), JSON.stringify(result, null, 2), 'utf-8');
-    return result;
+    const described = describeOptimizationResult(result);
+    writeFileSync(join(artifacts.runDir, 'execution_result.json'), JSON.stringify(described, null, 2), 'utf-8');
+    return described;
 }

package/dist/optimize/measurements.d.ts

@@ -0,0 +1,55 @@
+import { type MeasurementEnvelope, type MeasurementRequirements, type MeasurementCompatibility, type MeasurementCompletion, type MeasurementReason } from '../agent/runtime/measurements.js';
+import type { OptimizationExecutionResult } from './adapters/types.js';
+/** An adapter-captured copy of reported data. This is not a trusted host receipt. */
+export interface OptimizationMeasurementSource {
+    schemaVersion: 1;
+    sourceId: string;
+    sourceSha256: string;
+    sizeBytes: number;
+    complete: boolean;
+    rawOutput: string | null;
+}
+export interface OptimizationMeasurementDeclaration {
+    schemaVersion: 1;
+    objectiveKind: string;
+    direction: 'minimize' | 'maximize';
+    requirements: MeasurementRequirements;
+    envelope: MeasurementEnvelope;
+    baseline?: MeasurementEnvelope;
+}
+export interface OptimizationMeasurementReport {
+    compatibility: MeasurementCompatibility;
+    completion: MeasurementCompletion;
+    verification: 'unknown';
+    benchmarkEligibility: 'unknown';
+    sourceId: string | null;
+    sourceSha256: string | null;
+    runId: string | null;
+    declaredSource: MeasurementEnvelope['source'] | null;
+    reasons: MeasurementReason[];
+    objectiveKind: string | null;
+    direction: 'minimize' | 'maximize' | null;
+    value: number | null;
+    baselineValue: number | null;
+    improved: boolean | null;
+}
+/** Recompute from captured bytes on every read; saved reports and scalar ok/improved flags confer no qualification. */
+export declare function assessOptimizationResult(result: OptimizationExecutionResult): OptimizationMeasurementReport;
+export declare function compareOptimizationResults(base: OptimizationExecutionResult, candidate: OptimizationExecutionResult): {
+    compatibility: MeasurementCompatibility;
+    reasons: MeasurementReason[];
+    baseline: OptimizationMeasurementReport;
+    candidate: OptimizationMeasurementReport;
+};
+export declare function describeOptimizationResult(result: OptimizationExecutionResult): OptimizationExecutionResult;
+/** Preserve exact bounded producer bytes and their hash; do not truncate or infer a missing declaration from scalars. */
+export declare function captureOptimizationMeasurement(result: OptimizationExecutionResult, sourceId: string, rawOutput: string, complete: boolean): OptimizationExecutionResult;
+/** Adapter-owned producer contract for its parsed summary, not a scientific smoke test. */
+export interface AdapterSummaryComparison {
+    runId: string;
+    unit: string;
+    selection: Record<string, string | number | boolean | null>;
+}
+/** Emit a source-linked declaration from this adapter invocation. Historical
+ * scalar artifacts still require their original explicit declaration. */
+export declare function captureAdapterOptimizationMeasurement(result: OptimizationExecutionResult, sourceId: string, rawOutput: string, complete: boolean, comparison: AdapterSummaryComparison): OptimizationExecutionResult;

package/dist/optimize/measurements.js

@@ -0,0 +1,173 @@
+import { createHash } from 'node:crypto';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { assessMeasurements, compareMeasurements, parseMeasurementEnvelope, parseMeasurementRequirements, MEASUREMENT_MAX_ENVELOPE_BYTES } from '../agent/runtime/measurements.js';
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    if (value && typeof value === 'object')
+        return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`).join(',')}}`;
+    return JSON.stringify(value);
+}
+function contractKey(declaration) {
+    const r = declaration.requirements;
+    return canonical({ objectiveKind: declaration.objectiveKind, direction: declaration.direction, requirements: {
+            ...r, metricIds: [...r.metricIds].sort(), smokeFields: [...r.smokeFields].sort(), expectedRanks: [...r.expectedRanks].sort((a, b) => a - b),
+        } });
+}
+function declaration(source) {
+    if (!source || source.schemaVersion !== 1 || source.complete !== true || typeof source.sourceId !== 'string' || !source.sourceId.trim()
+        || Buffer.byteLength(source.sourceId) > 4096 || /[\u0000-\u001f\u007f]/u.test(source.sourceId)
+        || typeof source.sourceSha256 !== 'string' || !/^[a-f0-9]{64}$/.test(source.sourceSha256)
+        || typeof source.rawOutput !== 'string' || Buffer.byteLength(source.rawOutput) > MEASUREMENT_MAX_ENVELOPE_BYTES
+        || source.sizeBytes !== Buffer.byteLength(source.rawOutput)
+        || createHash('sha256').update(source.rawOutput).digest('hex') !== source.sourceSha256)
+        return null;
+    try {
+        const payload = JSON.parse(source.rawOutput);
+        if (!payload || typeof payload !== 'object' || Array.isArray(payload))
+            return null;
+        const value = payload.optimizationMeasurement;
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return null;
+        const record = value;
+        if (record.schemaVersion !== 1 || Object.keys(record).some(key => !['schemaVersion', 'objectiveKind', 'direction', 'requirements', 'envelope', 'baseline'].includes(key))
+            || typeof record.objectiveKind !== 'string' || !record.objectiveKind.trim() || Buffer.byteLength(record.objectiveKind) > 128
+            || /[\u0000-\u001f\u007f]/u.test(record.objectiveKind) || (record.direction !== 'minimize' && record.direction !== 'maximize'))
+            return null;
+        const requirements = parseMeasurementRequirements(record.requirements), envelope = parseMeasurementEnvelope(record.envelope);
+        const baseline = record.baseline === undefined ? undefined : parseMeasurementEnvelope(record.baseline);
+        if (!requirements || !envelope || baseline === null)
+            return null;
+        return { schemaVersion: 1, objectiveKind: record.objectiveKind, direction: record.direction, requirements, envelope,
+            ...(baseline === undefined ? {} : { baseline }) };
+    }
+    catch {
+        return null;
+    }
+}
+function objectiveValue(envelope, requirements) {
+    const report = assessMeasurements(envelope, requirements);
+    if (report.compatibility !== 'compatible' || report.completion !== 'reported_pass')
+        return null;
+    return requirements.aggregation === 'sum_exclusive' ? report.aggregate : report.values.length === 1 ? report.values[0].value : null;
+}
+/** Recompute from captured bytes on every read; saved reports and scalar ok/improved flags confer no qualification. */
+export function assessOptimizationResult(result) {
+    const d = declaration(result.measurement);
+    const report = { compatibility: 'unknown', completion: 'unknown', verification: 'unknown', benchmarkEligibility: 'unknown',
+        sourceId: null, sourceSha256: null, runId: null, declaredSource: null, reasons: [], objectiveKind: null, direction: null, value: null, baselineValue: null, improved: null };
+    const source = result.measurement;
+    if (source && source.schemaVersion === 1 && typeof source.sourceId === 'string' && source.sourceId.trim()
+        && Buffer.byteLength(source.sourceId) <= 4096 && !/[\u0000-\u001f\u007f]/u.test(source.sourceId)
+        && typeof source.sourceSha256 === 'string' && /^[a-f0-9]{64}$/.test(source.sourceSha256)) {
+        report.sourceId = source.sourceId;
+        report.sourceSha256 = source.sourceSha256;
+    }
+    if (!d) {
+        report.reasons.push({ code: result.measurement ? 'invalid_capture_or_declaration' : 'legacy_scalar',
+            message: 'A bounded intact captured source with an explicit measurement declaration is required; scalar artifacts remain readable.' });
+    }
+    else {
+        const assessment = assessMeasurements(d.envelope, d.requirements);
+        Object.assign(report, { compatibility: assessment.compatibility, completion: assessment.completion, sourceId: result.measurement.sourceId,
+            sourceSha256: result.measurement.sourceSha256, runId: assessment.runId, declaredSource: assessment.source,
+            reasons: [...assessment.reasons], objectiveKind: d.objectiveKind, direction: d.direction });
+        report.value = objectiveValue(d.envelope, d.requirements);
+        if (assessment.compatibility === 'compatible' && report.value === null) {
+            report.compatibility = 'unknown';
+            report.reasons.push({ code: 'ambiguous_objective', message: 'Declare one selected objective or an explicit compatible aggregation.' });
+        }
+        if (d.baseline && compareMeasurements(d.baseline, d.envelope, d.requirements).compatibility === 'compatible') {
+            report.baselineValue = objectiveValue(d.baseline, d.requirements);
+            if (report.value !== null && report.baselineValue !== null)
+                report.improved = d.direction === 'minimize'
+                    ? report.value < report.baselineValue : report.value > report.baselineValue;
+        }
+    }
+    if (!result.ok || result.status !== 'completed' || (result.exitCode !== undefined && result.exitCode !== 0)) {
+        report.compatibility = 'incompatible';
+        report.completion = 'reported_fail';
+        report.value = null;
+        report.improved = null;
+        report.reasons.push({ code: 'execution_not_completed', message: 'The adapter execution did not complete successfully.' });
+    }
+    return report;
+}
+export function compareOptimizationResults(base, candidate) {
+    const baseline = assessOptimizationResult(base), next = assessOptimizationResult(candidate);
+    const a = declaration(base.measurement), b = declaration(candidate.measurement);
+    if (!a || !b || baseline.compatibility !== 'compatible' || next.compatibility !== 'compatible')
+        return {
+            compatibility: baseline.compatibility === 'incompatible' || next.compatibility === 'incompatible' ? 'incompatible' : 'unknown',
+            reasons: [{ code: 'unqualified_comparison', message: 'Both results need a complete comparable reported objective.' }], baseline, candidate: next
+        };
+    if (contractKey(a) !== contractKey(b))
+        return { compatibility: 'incompatible',
+            reasons: [{ code: 'contract_mismatch', message: 'Objective, direction and declared measurement requirements must match.' }], baseline, candidate: next };
+    const compared = compareMeasurements(a.envelope, b.envelope, a.requirements);
+    return { compatibility: compared.compatibility, reasons: compared.reasons, baseline, candidate: next };
+}
+export function describeOptimizationResult(result) {
+    const measurementReport = assessOptimizationResult(result);
+    const prefix = '[measurement-contract] ';
+    const projection = `${prefix}comparison=${measurementReport.compatibility}; completion=${measurementReport.completion}; `
+        + `verification=${measurementReport.verification}; benchmarkEligibility=${measurementReport.benchmarkEligibility}; `
+        + `source=${measurementReport.sourceId ?? 'unavailable'}; sha256=${measurementReport.sourceSha256 ?? 'unavailable'}; `
+        + `run=${measurementReport.runId ?? 'unknown'}; reasons=${measurementReport.reasons.map(reason => reason.code).join(',') || 'none'}.`;
+    // Replacing only this canonical projection prevents stale positive notes on repeated/failed replay.
+    return { ...result, measurementReport, notes: [...result.notes.filter(note => !note.startsWith(prefix)), projection] };
+}
+/** Preserve exact bounded producer bytes and their hash; do not truncate or infer a missing declaration from scalars. */
+export function captureOptimizationMeasurement(result, sourceId, rawOutput, complete) {
+    const sizeBytes = Buffer.byteLength(rawOutput);
+    const measured = { ...result, measurement: { schemaVersion: 1, sourceId,
+            complete, sourceSha256: createHash('sha256').update(rawOutput).digest('hex'), sizeBytes,
+            rawOutput: sizeBytes <= MEASUREMENT_MAX_ENVELOPE_BYTES ? rawOutput : null } };
+    return describeOptimizationResult(measured);
+}
+/** Emit a source-linked declaration from this adapter invocation. Historical
+ * scalar artifacts still require their original explicit declaration. */
+export function captureAdapterOptimizationMeasurement(result, sourceId, rawOutput, complete, comparison) {
+    // Never replace or repair a producer's existing declaration, including an
+    // invalid one. Its original captured bytes keep their existing admission.
+    try {
+        const payload = JSON.parse(rawOutput);
+        if (payload && typeof payload === 'object' && Object.hasOwn(payload, 'optimizationMeasurement'))
+            return captureOptimizationMeasurement(result, sourceId, rawOutput, complete);
+    }
+    catch { /* Existing native evaluators also emit log-prefixed/text summaries. */ }
+    const metrics = result.metrics;
+    if (!complete || !result.ok || result.status !== 'completed' || !result.adapterId || !metrics
+        || typeof metrics.candidateValue !== 'number' || !Number.isFinite(metrics.candidateValue) || metrics.candidateValue < 0
+        || Buffer.byteLength(rawOutput) > MEASUREMENT_MAX_ENVELOPE_BYTES)
+        return captureOptimizationMeasurement(result, sourceId, rawOutput, complete);
+    const rawSha256 = createHash('sha256').update(rawOutput).digest('hex');
+    const workload = { id: `${result.adapterId}:reported-summary`, stage: 'candidate-evaluation', inputShape: {
+            selectionSha256: createHash('sha256').update(canonical(comparison.selection)).digest('hex'),
+        } };
+    const instrumentation = { mode: 'adapter-reported-summary', version: '1', synchronization: 'diagnostic',
+        runtimePath: `ztc/optimize/${result.adapterId}` };
+    const requirements = { workload, instrumentation, metricIds: ['reported-objective'],
+        unit: comparison.unit, timingDomain: 'adapter-summary', scope: 'selected-evaluator', worldSize: 1,
+        expectedRanks: [0], smokeFields: ['reported-objective'], aggregation: 'none' };
+    const envelope = (value, runId) => ({ schemaVersion: 1, runId,
+        source: { revision: 'ztc-adapter-summary-v1', artifactSha256: rawSha256 }, workload, instrumentation,
+        completion: { status: 'completed', passed: true },
+        // This smoke records successful summary parsing on the named adapter path.
+        // Diagnostic instrumentation prevents it claiming a production benchmark.
+        smoke: { mode: instrumentation.mode, runtimePath: instrumentation.runtimePath, fields: ['reported-objective'], passed: true },
+        metrics: [{ id: 'reported-objective', value, unit: comparison.unit, timingDomain: requirements.timingDomain,
+                scope: requirements.scope, rank: 0, worldSize: 1, coverage: 'exclusive' }] });
+    const declared = { schemaVersion: 1, objectiveKind: metrics.objectiveKind,
+        direction: metrics.direction, requirements, envelope: envelope(metrics.candidateValue, comparison.runId),
+        ...(typeof metrics.baselineValue === 'number' && Number.isFinite(metrics.baselineValue) && metrics.baselineValue >= 0
+            ? { baseline: envelope(metrics.baselineValue, `${comparison.runId}:baseline`) } : {}) };
+    const captured = JSON.stringify({ optimizationMeasurement: declared,
+        adapterSummary: { sourceId, sourceSha256: rawSha256, rawOutput, selection: comparison.selection,
+            scope: 'reported adapter summary only; source verification and benchmark eligibility remain unknown' } });
+    const declarationPath = join(result.runDir, 'adapter_measurement.json');
+    writeFileSync(declarationPath, captured, 'utf8');
+    return captureOptimizationMeasurement(result, declarationPath, captured, complete);
+}

package/dist/optimize/results.d.ts

@@ -1,3 +1,4 @@
 import type { OptimizationExecutionResult } from './adapters/types.js';
+/** A score of comparable reported data, never source verification or benchmark admission. */
 export declare function result_score(result: OptimizationExecutionResult): number | null;
 export declare function is_better_result(currentBest: OptimizationExecutionResult | null, next: OptimizationExecutionResult): boolean;