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

package/dist/agent/loop_policy.d.ts

@@ -1,3 +1,4 @@
+import type { ManagedCommandObservation } from './runtime/command_jobs.js';
 /**
  * Shared loop-policy helpers applied by BOTH run loops (Agent.run and
  * SubAgent.run) so the two cannot drift (Eng review A5). Pure and stateless
@@ -8,10 +9,12 @@
  * input, and result content, appends a corrective hint when the SAME call
  * (name + canonical input) produced a byte-identical result to a previous call
  * in this run — the non-progressing repeat behind F8 churn / F1 re-fire.
- * Result-equality (not raw repeat count) is what spares legitimate polling and
- * retries whose output changes between calls.
+ * Changed results and host-verified silent managed reads are legitimate
+ * observations, so neither receives a corrective warning.
  */
-export declare function createRepeatGuard(): (name: string, input: unknown, content: string) => string;
+export declare function createRepeatGuard(): (name: string, input: unknown, content: string, managedCommand?: ManagedCommandObservation) => string;
+/** This metadata is supplied by the host tools, never inferred from result text. */
+export declare function isHealthyManagedCommandRead(observation?: ManagedCommandObservation): boolean;
 /** Suffix createRepeatGuard appends to a repeated identical result. */
 export declare const REPEAT_GUARD_MARKER = "\n\n[repeat-guard] ";
 /**

package/dist/agent/loop_policy.js

@@ -8,12 +8,14 @@
  * input, and result content, appends a corrective hint when the SAME call
  * (name + canonical input) produced a byte-identical result to a previous call
  * in this run — the non-progressing repeat behind F8 churn / F1 re-fire.
- * Result-equality (not raw repeat count) is what spares legitimate polling and
- * retries whose output changes between calls.
+ * Changed results and host-verified silent managed reads are legitimate
+ * observations, so neither receives a corrective warning.
  */
 export function createRepeatGuard() {
     const seen = new Map();
-    return (name, input, content) => {
+    return (name, input, content, managedCommand) => {
+        if (isHealthyManagedCommandRead(managedCommand))
+            return content;
         let sig;
         try {
             // NUL separator: unambiguous by construction — it cannot appear in a tool
@@ -31,6 +33,13 @@ export function createRepeatGuard() {
         return content;
     };
 }
+/** This metadata is supplied by the host tools, never inferred from result text. */
+export function isHealthyManagedCommandRead(observation) {
+    return observation?.kind === 'read'
+        && observation.result.status === 'running'
+        && observation.result.output === ''
+        && observation.result.has_more === false;
+}
 /** Suffix createRepeatGuard appends to a repeated identical result. */
 export const REPEAT_GUARD_MARKER = '\n\n[repeat-guard] ';
 /**

package/dist/agent/measurement_guidance.d.ts

@@ -0,0 +1,2 @@
+/** Guidance for the generic retained-source checker, only when that tool is reachable. */
+export declare const MEASUREMENT_EVIDENCE_GUIDANCE: string;

package/dist/agent/measurement_guidance.js

@@ -0,0 +1,5 @@
+/** Guidance for the generic retained-source checker, only when that tool is reachable. */
+export const MEASUREMENT_EVIDENCE_GUIDANCE = `
+MEASUREMENT VALIDATION — before ranking a reported optimization target, establish its metric definition and selected runtime path. Discover measurement_report with tool_search and assess original retained managed-command observation IDs against explicit workload/stage/input shape, units, timing domain, scope/ranks and instrumentation requirements. Use the measurement-validation skill for the producer envelope and workflow.
+Compatibility does not establish source verification or benchmark eligibility; both remain unknown. A running startup artifact with passed=false is incomplete, not a failed final run. Demonstrate the expected metric field in a small smoke in the requested mode/path before an expensive full run. Never sum inclusive parent/child spans or overlapping ranks as exclusive wall time. Keep unexplained residuals unattributed hypotheses, not measured removable performance wins. No report grants execution authorization.
+`.trim();

package/dist/agent/request_encoder.d.ts

@@ -15,9 +15,12 @@
  * field write. The tool-result selector itself stays agent-owned: the agent
  * computes the verdict and passes it in; the encoder only assembles blocks.
  */
-import { Message } from '../types.js';
+import { Message, ToolDefinition } from '../types.js';
 import { LlmMessage, RequestContentBlock } from './backends/index.js';
 export interface EncodeDeps {
+    preserveNativeHistory?: boolean;
+    model?: string;
+    nativeContextId?: string;
     /**
      * Per-request tool-result selector verdict (tool_use_id -> rendered content),
      * or null when no tool results are present. Computed by the agent (selector is
@@ -45,12 +48,14 @@ export interface EncodeResult {
      */
     transientOverageTokens: number;
 }
+export declare const STABLE_RESULT_LIMIT = 4096;
 export declare class RequestEncoder {
     private readonly deps;
     private overage;
     constructor(deps: EncodeDeps);
     /** Full request encoding: role filter + per-message content + same-role merge. */
     encode(messages: Message[]): EncodeResult;
+    private freezeContent;
     /**
      * Build the request content for a single message string: tool-result JSON ->
      * tool_result blocks (selector-rendered), `[image …]`/`[video …]` -> media
@@ -64,3 +69,5 @@ export declare class RequestEncoder {
     private parseToolResultForImages;
     private buildToolResultBlocks;
 }
+/** Provider reasoning binds the system prompt and ordered tool vocabulary. */
+export declare function nativeHistoryContextId(system: string, tools: ToolDefinition[]): string;

package/dist/agent/request_encoder.js

@@ -15,12 +15,15 @@
  * field write. The tool-result selector itself stays agent-owned: the agent
  * computes the verdict and passes it in; the encoder only assembles blocks.
  */
+import { createHash } from 'node:crypto';
 import { isMirrorMediaPath } from '../utils/mirror_media.js';
+import { readDurableSessionImageSync, SessionMediaError } from '../session_media.js';
 import { parseImageToolResult } from './tool_result_parsing.js';
+import { assistantClaimReplayContent } from './claim_observation.js';
 const OLD_RESULT_CAP = 2000;
 // Rewriting a near-cap result saves little but changes the cacheable history.
 // Keep small results stable; large historical results still use the 2K cap.
-const STABLE_RESULT_LIMIT = 4096;
+export const STABLE_RESULT_LIMIT = 4096;
 export class RequestEncoder {
     deps;
     overage = 0;
@@ -29,7 +32,7 @@ export class RequestEncoder {
     }
     /** Full request encoding: role filter + per-message content + same-role merge. */
     encode(messages) {
-        const formatted = messages
+        const eligibleMessages = messages
             .filter((m) => {
             if (m.role !== 'user' && m.role !== 'assistant')
                 return false;
@@ -37,15 +40,44 @@ export class RequestEncoder {
                 return false;
             return true;
         })
+            .flatMap(message => {
+            if (!this.deps.preserveNativeHistory || message.role !== 'assistant' || !Array.isArray(message.nativeContent))
+                return [message];
+            const observation = assistantClaimReplayContent(message);
+            if (observation === message.content
+                || message.nativeContent.some(block => block.type === 'text' && block.text === observation))
+                return [message];
+            // Opaque provider blocks stay unchanged. Place the validated historical
+            // observation before this assistant so its tool/result pair remains
+            // adjacent and the current authored request retains the final row.
+            return [{
+                    id: `${message.id}_claim_observation`, role: 'user',
+                    content: observation, timestamp: message.timestamp,
+                    metadata: { synthetic: true, hostContext: true, preserveUserBoundary: true },
+                }, message];
+        });
+        const formatted = eligibleMessages
             .map(m => {
+            const assistantContent = m.role === 'assistant' ? assistantClaimReplayContent(m) : m.content;
+            if (this.deps.preserveNativeHistory && m.nativeContent !== undefined && m.nativeModel === this.deps.model
+                && m.nativeContextId === this.deps.nativeContextId) {
+                if (typeof m.nativeContent === 'string' && assistantContent !== m.content) {
+                    // The host may have observed this claim after its plain native text
+                    // was frozen. Retain the admitted qualification on every replay.
+                    this.freezeContent(m, assistantContent);
+                    return { role: m.role, content: assistantContent };
+                }
+                return { role: m.role, content: structuredClone(m.nativeContent) };
+            }
             if (m.role === 'user') {
-                // R0: a compaction summary must reach the model as plain text. Skip
-                // buildUserContentBlocks so its tool-result-array heuristic can't
-                // re-parse (and drop) a summary that happens to quote JSON.
-                if (m.metadata?.compactionSummary) {
+                // Summaries and host observations quote source text. Preserve those
+                // quotes literally rather than treating them as new media directives
+                // or tool results. Other synthetic messages can be real tool results.
+                if (m.metadata?.compactionSummary || m.metadata?.hostContext === true) {
                     return { role: m.role, content: m.content };
                 }
                 const content = this.buildUserContentBlocks(m.content, m.attachments || []);
+                this.freezeContent(m, content);
                 return {
                     role: m.role,
                     content
@@ -54,13 +86,20 @@ export class RequestEncoder {
             const reasoning = typeof m.metadata?.reasoningContent === 'string'
                 ? m.metadata.reasoningContent
                 : undefined;
+            // A model switch starts a fresh reasoning context. Preserve factual
+            // native text/tool blocks, but never send another model's signatures.
+            if (this.deps.preserveNativeHistory && Array.isArray(m.nativeContent)) {
+                const content = m.nativeContent.filter(block => block.type !== 'thinking' && block.type !== 'redacted_thinking');
+                this.freezeContent(m, content);
+                return { role: m.role, content };
+            }
             // Assistant message - may need to include tool_use blocks
             if (m.toolCalls && m.toolCalls.length > 0) {
                 // Build content array with text and tool_use blocks
                 const contentBlocks = [];
                 // Add text content if present
-                if (m.content && m.content.trim() && m.content !== '[Using tools...]') {
-                    contentBlocks.push({ type: 'text', text: m.content });
+                if (assistantContent && assistantContent.trim() && assistantContent !== '[Using tools...]') {
+                    contentBlocks.push({ type: 'text', text: assistantContent });
                 }
                 // Add tool_use blocks
                 for (const tc of m.toolCalls) {
@@ -71,6 +110,7 @@ export class RequestEncoder {
                         input: tc.args
                     });
                 }
+                this.freezeContent(m, contentBlocks);
                 return {
                     role: m.role,
                     content: contentBlocks,
@@ -78,9 +118,10 @@ export class RequestEncoder {
                 };
             }
             // Plain text assistant message
+            this.freezeContent(m, assistantContent);
             return {
                 role: m.role,
-                content: m.content,
+                content: assistantContent,
                 ...(reasoning ? { reasoning } : {}),
             };
         });
@@ -88,8 +129,14 @@ export class RequestEncoder {
         // Two sources: (1) repair injects synthetic tool_result user before real user prompt,
         // (2) multi-iteration runs where formatMessages filters intervening role:'tool' messages
         const merged = [];
-        for (const msg of formatted) {
-            if (merged.length > 0 && msg.role === merged[merged.length - 1].role) {
+        const preservesUserBoundary = (message) => message?.role === 'user' && message.metadata?.hostContext === true
+            && message.metadata.preserveUserBoundary === true;
+        for (const [index, msg] of formatted.entries()) {
+            // A historical host handoff is its own user row on both sides. Keep this
+            // metadata local to encoding; ordinary user and tool-result merging stays intact.
+            if (merged.length > 0 && msg.role === merged[merged.length - 1].role
+                && !preservesUserBoundary(eligibleMessages[index])
+                && !preservesUserBoundary(eligibleMessages[index - 1])) {
                 const prev = merged[merged.length - 1];
                 const prevBlocks = this.toContentBlocks(prev.content);
                 const currBlocks = this.toContentBlocks(msg.content);
@@ -108,6 +155,13 @@ export class RequestEncoder {
         }
         return { messages: merged, transientOverageTokens: this.overage };
     }
+    freezeContent(message, content) {
+        if (!this.deps.preserveNativeHistory)
+            return;
+        message.nativeContent = structuredClone(content);
+        message.nativeModel = this.deps.model;
+        message.nativeContextId = this.deps.nativeContextId;
+    }
     /**
      * Build the request content for a single message string: tool-result JSON ->
      * tool_result blocks (selector-rendered), `[image …]`/`[video …]` -> media
@@ -132,10 +186,10 @@ export class RequestEncoder {
                     // block (content must be a string for the API), not as undefined —
                     // which would crash parseImageToolResult and silently degrade the
                     // whole message to plain text, breaking tool_use/tool_result pairing.
-                    content: verdict?.get(r.tool_use_id)
+                    content: (verdict?.get(r.tool_use_id)
                         ?? this.deps.renderForContext(r.tool_use_id)
                         ?? r.content
-                        ?? '',
+                        ?? '') + (typeof r.context_annotation === 'string' ? r.context_annotation : ''),
                 }));
                 return this.buildToolResultBlocks(rerendered);
             }
@@ -211,17 +265,31 @@ export class RequestEncoder {
     buildAttachmentBlocks(attachments) {
         const blocks = [];
         for (const attachment of attachments) {
-            if (attachment.kind !== 'image' || !attachment.localPath)
-                continue;
-            // Structured attachments are read off disk (loadImageBlock -> readFileSync). A child
-            // pane receives them from the mirror over an unauthenticated wire, so a forged localPath
-            // pointing outside the mirror media root would be an arbitrary server-file read. Only
-            // genuine mirror uploads live under MIRROR_MEDIA_ROOT; refuse anything else.
-            if (!isMirrorMediaPath(attachment.localPath))
+            if (attachment.kind !== 'image')
                 continue;
-            const block = this.deps.loadImageBlock(attachment.localPath);
-            if (block)
-                blocks.push(block);
+            try {
+                const durable = readDurableSessionImageSync(attachment);
+                if (durable) {
+                    blocks.push({ type: 'image', mediaType: durable.mediaType,
+                        data: durable.data.toString('base64'), path: durable.localPath });
+                    continue;
+                }
+                // Keep legacy staging references confined to the admitted upload root.
+                if (isMirrorMediaPath(attachment.localPath)) {
+                    const block = this.deps.loadImageBlock(attachment.localPath);
+                    if (block) {
+                        blocks.push(block);
+                        continue;
+                    }
+                }
+            }
+            catch (error) {
+                if (!(error instanceof SessionMediaError))
+                    throw error;
+            }
+            const leaf = typeof attachment.name === 'string' ? attachment.name.split(/[\\/]/).pop() ?? 'image' : 'image';
+            const name = leaf.replace(/[\u0000-\u001f\u007f]/g, ' ').slice(0, 120) || 'image';
+            blocks.push({ type: 'text', text: `Image attachment "${name}" is unavailable. Reattach the image to inspect it.` });
         }
         return blocks;
     }
@@ -277,3 +345,7 @@ export class RequestEncoder {
         });
     }
 }
+/** Provider reasoning binds the system prompt and ordered tool vocabulary. */
+export function nativeHistoryContextId(system, tools) {
+    return createHash('sha256').update(JSON.stringify({ system, tools })).digest('hex');
+}

package/dist/agent/runtime/benchmark_comparison.d.ts

@@ -0,0 +1,30 @@
+import type { BenchmarkVerifierDecision } from './benchmark_contract.js';
+import type { CommandVerificationReceipt } from './source_verification_contract.js';
+export interface BenchmarkComparisonSource {
+    observation_id: string;
+    receipt_id: string;
+    source_id: string;
+    program_sha256: string;
+    value_ms: number;
+}
+export interface BenchmarkComparisonDecision {
+    schema_version: 1;
+    adapter_id: 'cpu_integer_sum_comparison';
+    scope: 'benchmark:cpu_integer_sum';
+    outcome: 'comparable' | 'incompatible' | 'unknown';
+    benchmark_eligibility: 'eligible' | 'ineligible' | 'unknown';
+    baseline: BenchmarkComparisonSource | null;
+    candidate: BenchmarkComparisonSource | null;
+    delta_ms: number | null;
+    relative_change_percent: number | null;
+    reason: string;
+}
+export interface RegisteredBenchmarkObservation {
+    id: string;
+    receipt: CommandVerificationReceipt;
+    decision: BenchmarkVerifierDecision;
+}
+/** Historical comparison metadata never invents another execution or verifies the observation itself. */
+export declare function parseBenchmarkComparisonDecision(value: unknown): BenchmarkComparisonDecision | null;
+/** Compare declared fixture conditions, never infer causal improvement or a plateau from a delta. */
+export declare function compareRegisteredBenchmarks(baseline: RegisteredBenchmarkObservation | null, candidate: RegisteredBenchmarkObservation | null): BenchmarkComparisonDecision;

package/dist/agent/runtime/benchmark_comparison.js

@@ -0,0 +1,94 @@
+const encoded = new TextEncoder();
+function object(value, fields) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new TypeError('Invalid comparison object');
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null)
+        throw new TypeError('Invalid comparison prototype');
+    const row = value;
+    if (Object.keys(row).length !== fields.length || fields.some(key => !Object.hasOwn(row, key)))
+        throw new TypeError('Invalid comparison fields');
+    return row;
+}
+const hash = (value) => typeof value === 'string' && /^[a-f0-9]{64}$/u.test(value);
+const text = (value, limit) => typeof value === 'string' && value.trim().length > 0
+    && encoded.encode(value).length <= limit && !/[\u0000-\u001f\u007f]/u.test(value);
+function source(value) {
+    if (value === null)
+        return null;
+    const row = object(value, ['observation_id', 'receipt_id', 'source_id', 'program_sha256', 'value_ms']);
+    if (!text(row.observation_id, 256) || !text(row.receipt_id, 256) || !hash(row.source_id) || !hash(row.program_sha256)
+        || typeof row.value_ms !== 'number' || !Number.isFinite(row.value_ms) || row.value_ms <= 0 || row.value_ms > 60000) {
+        throw new TypeError('Invalid bounded comparison source');
+    }
+    return row;
+}
+/** Historical comparison metadata never invents another execution or verifies the observation itself. */
+export function parseBenchmarkComparisonDecision(value) {
+    try {
+        if (encoded.encode(JSON.stringify(value)).length > 4096)
+            return null;
+        const row = object(value, ['schema_version', 'adapter_id', 'scope', 'outcome', 'benchmark_eligibility', 'baseline', 'candidate',
+            'delta_ms', 'relative_change_percent', 'reason']);
+        if (row.schema_version !== 1 || row.adapter_id !== 'cpu_integer_sum_comparison' || row.scope !== 'benchmark:cpu_integer_sum'
+            || !text(row.reason, 512) || !['comparable', 'incompatible', 'unknown'].includes(String(row.outcome)))
+            return null;
+        const baseline = source(row.baseline);
+        const candidate = source(row.candidate);
+        if (row.outcome === 'comparable') {
+            if (row.benchmark_eligibility !== 'eligible' || !baseline || !candidate
+                || baseline.observation_id === candidate.observation_id || baseline.receipt_id === candidate.receipt_id
+                || row.delta_ms !== candidate.value_ms - baseline.value_ms
+                || typeof row.relative_change_percent !== 'number' || !Number.isFinite(row.relative_change_percent)
+                || row.relative_change_percent !== (candidate.value_ms - baseline.value_ms) / baseline.value_ms * 100)
+                return null;
+        }
+        else if (row.delta_ms !== null || row.relative_change_percent !== null
+            || row.benchmark_eligibility !== (row.outcome === 'incompatible' ? 'ineligible' : 'unknown'))
+            return null;
+        return structuredClone(row);
+    }
+    catch {
+        return null;
+    }
+}
+const describe = (observed) => observed.decision.measurement
+    && observed.decision.program_sha256 ? { observation_id: observed.id, receipt_id: observed.receipt.receipt_id,
+    source_id: observed.receipt.source.source_id, program_sha256: observed.decision.program_sha256,
+    value_ms: observed.decision.measurement.value_ms } : null;
+function sameFields(first, second, fields) {
+    const left = first;
+    const right = second;
+    return fields.every(key => left[key] === right[key]);
+}
+/** Compare declared fixture conditions, never infer causal improvement or a plateau from a delta. */
+export function compareRegisteredBenchmarks(baseline, candidate) {
+    const result = { schema_version: 1, adapter_id: 'cpu_integer_sum_comparison', scope: 'benchmark:cpu_integer_sum',
+        outcome: 'unknown', benchmark_eligibility: 'unknown', baseline: baseline ? describe(baseline) : null,
+        candidate: candidate ? describe(candidate) : null, delta_ms: null, relative_change_percent: null,
+        reason: 'Two complete retained host-admitted eligible CPU measurements are required.' };
+    if (!baseline || !candidate || baseline.decision.benchmark_eligibility !== 'eligible'
+        || candidate.decision.benchmark_eligibility !== 'eligible' || !result.baseline || !result.candidate)
+        return result;
+    result.outcome = 'incompatible';
+    result.benchmark_eligibility = 'ineligible';
+    if (baseline.id === candidate.id || baseline.receipt.receipt_id === candidate.receipt.receipt_id) {
+        result.reason = 'Two aliases of the same original run are not independent measurements.';
+        return result;
+    }
+    const first = baseline.decision;
+    const second = candidate.decision;
+    if (first.recipe_sha256 !== second.recipe_sha256 || first.checker_sha256 !== second.checker_sha256
+        || !sameFields(first.conditions, second.conditions, ['host_instance_id', 'cpu_model', 'logical_cpus', 'os_release'])
+        || !sameFields(baseline.receipt.environment, candidate.receipt.environment, ['platform', 'arch', 'node_version', 'declared_id'])
+        || !first.workload || !second.workload || !sameFields(first.workload, second.workload, ['id', 'input_sha256', 'length', 'iterations', 'warmup', 'samples'])) {
+        result.reason = 'Workload, checker, runner or declared execution/measurement conditions differ.';
+        return result;
+    }
+    result.outcome = 'comparable';
+    result.benchmark_eligibility = 'eligible';
+    result.delta_ms = result.candidate.value_ms - result.baseline.value_ms;
+    result.relative_change_percent = result.delta_ms / result.baseline.value_ms * 100;
+    result.reason = 'Independent registered measurements share the declared workload and conditions; no causal improvement or plateau is inferred.';
+    return result;
+}

package/dist/agent/runtime/benchmark_contract.d.ts

@@ -0,0 +1,48 @@
+import type { CommandVerificationReceipt } from './source_verification_contract.js';
+/** Eligibility is scoped to this registered CPU fixture and its captured measurement conditions. */
+export interface BenchmarkVerifierDecision {
+    schema_version: 1;
+    adapter_id: 'cpu_integer_sum';
+    recipe_version: 1;
+    execution: 'host_node_subprocess';
+    recipe_sha256: string;
+    receipt_id: string;
+    source_id: string;
+    scope: 'benchmark:cpu_integer_sum';
+    input_path: string;
+    config_path: string;
+    input_binding: 'immutable_bytes' | 'unknown';
+    outcome: 'passed' | 'failed' | 'unknown';
+    checks_total: number;
+    checks_passed: number;
+    reason: string;
+    benchmark_eligibility: 'eligible' | 'ineligible' | 'unknown';
+    variant: 'for_loop' | 'array_reduce' | null;
+    program_sha256: string | null;
+    checker_sha256: string;
+    conditions: {
+        host_instance_id: string;
+        cpu_model: string;
+        logical_cpus: number;
+        os_release: string;
+    };
+    workload: {
+        id: 'cpu_integer_sum/v1';
+        input_sha256: string;
+        length: number;
+        iterations: number;
+        warmup: number;
+        samples: number;
+    } | null;
+    measurement: {
+        samples_ms: number[];
+        value_ms: number;
+        unit: 'ms';
+        timing_domain: 'node_performance_now';
+        scope: 'integer_sum_kernel';
+        rank: 0;
+        world_size: 1;
+    } | null;
+}
+/** Decode a host-admitted decision; provider output must never enter this trusted channel. */
+export declare function parseBenchmarkVerifierDecision(value: unknown, receipt: CommandVerificationReceipt): BenchmarkVerifierDecision | null;

package/dist/agent/runtime/benchmark_contract.js

@@ -0,0 +1,90 @@
+const hash = (value) => typeof value === 'string' && /^[a-f0-9]{64}$/u.test(value);
+const integer = (value, low, high) => typeof value === 'number'
+    && Number.isSafeInteger(value) && value >= low && value <= high;
+const encoded = new TextEncoder();
+const text = (value, bound) => typeof value === 'string' && value.trim().length > 0
+    && encoded.encode(value).length <= bound && !/[\u0000-\u001f\u007f]/u.test(value);
+function object(value, fields) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new TypeError('Invalid benchmark object');
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null)
+        throw new TypeError('Invalid benchmark prototype');
+    const row = value;
+    if (Object.keys(row).length !== fields.length || fields.some(key => !Object.hasOwn(row, key))) {
+        throw new TypeError('Invalid benchmark fields');
+    }
+    return row;
+}
+/** Decode a host-admitted decision; provider output must never enter this trusted channel. */
+export function parseBenchmarkVerifierDecision(value, receipt) {
+    try {
+        if (encoded.encode(JSON.stringify(value)).length > 8192)
+            return null;
+        const row = object(value, ['schema_version', 'adapter_id', 'recipe_version', 'execution', 'recipe_sha256', 'receipt_id', 'source_id',
+            'scope', 'input_path', 'config_path', 'input_binding', 'outcome', 'checks_total', 'checks_passed', 'reason', 'benchmark_eligibility',
+            'variant', 'program_sha256', 'checker_sha256', 'conditions', 'workload', 'measurement']);
+        if (row.schema_version !== 1 || row.adapter_id !== 'cpu_integer_sum' || row.recipe_version !== 1
+            || row.execution !== 'host_node_subprocess' || row.scope !== 'benchmark:cpu_integer_sum'
+            || !hash(row.recipe_sha256) || row.recipe_sha256 !== receipt.command_sha256
+            || row.receipt_id !== receipt.receipt_id || row.source_id !== receipt.source.source_id
+            || receipt.command_kind !== 'host_verifier' || receipt.purpose !== 'benchmark' || receipt.scope !== row.scope
+            || receipt.source.origin !== 'local' || !hash(row.checker_sha256) || !text(row.reason, 512)
+            || !['immutable_bytes', 'unknown'].includes(String(row.input_binding))
+            || !['passed', 'failed', 'unknown'].includes(String(row.outcome))
+            || !['eligible', 'ineligible', 'unknown'].includes(String(row.benchmark_eligibility))
+            || !integer(row.checks_total, 0, 9) || !integer(row.checks_passed, 0, row.checks_total))
+            return null;
+        const input = receipt.source.files.find(file => file.path === row.input_path);
+        const config = receipt.source.files.find(file => file.path === row.config_path);
+        if (!input || !config || input.path === config.path || receipt.source.files.length !== 2)
+            return null;
+        if (row.variant !== null && row.variant !== 'for_loop' && row.variant !== 'array_reduce')
+            return null;
+        if (row.variant === null ? row.program_sha256 !== null : !hash(row.program_sha256))
+            return null;
+        const conditions = object(row.conditions, ['host_instance_id', 'cpu_model', 'logical_cpus', 'os_release']);
+        if (!hash(conditions.host_instance_id) || !text(conditions.cpu_model, 256) || !integer(conditions.logical_cpus, 1, 1024)
+            || !text(conditions.os_release, 128))
+            return null;
+        let workload = null;
+        if (row.workload !== null) {
+            workload = object(row.workload, ['id', 'input_sha256', 'length', 'iterations', 'warmup', 'samples']);
+            if (workload.id !== 'cpu_integer_sum/v1' || workload.input_sha256 !== input.sha256
+                || !integer(workload.length, 1, 1024) || !integer(workload.iterations, 1, 2048)
+                || !integer(workload.warmup, 0, 4) || !integer(workload.samples, 3, 9) || workload.samples % 2 === 0)
+                return null;
+        }
+        if (row.measurement !== null) {
+            const measured = object(row.measurement, ['samples_ms', 'value_ms', 'unit', 'timing_domain', 'scope', 'rank', 'world_size']);
+            if (!workload || measured.unit !== 'ms' || measured.timing_domain !== 'node_performance_now'
+                || measured.scope !== 'integer_sum_kernel' || measured.rank !== 0 || measured.world_size !== 1
+                || !Array.isArray(measured.samples_ms) || measured.samples_ms.length !== workload.samples
+                || measured.samples_ms.some(sample => typeof sample !== 'number' || !Number.isFinite(sample) || sample <= 0 || sample > 60000))
+                return null;
+            const sorted = [...measured.samples_ms].sort((a, b) => a - b);
+            if (measured.value_ms !== sorted[Math.floor(sorted.length / 2)])
+                return null;
+        }
+        if (row.outcome === 'unknown') {
+            if (row.checks_total !== 0 || row.checks_passed !== 0 || row.measurement !== null || row.benchmark_eligibility === 'eligible')
+                return null;
+        }
+        else {
+            if (row.input_binding !== 'immutable_bytes' || receipt.source.coverage !== 'complete'
+                || input.kind !== 'file' || config.kind !== 'file' || input.bytes > 65536 || config.bytes > 65536
+                || !workload || row.measurement === null || row.variant === null || row.checks_total !== workload.samples
+                || receipt.process_outcome !== 'passed')
+                return null;
+            if (row.outcome === 'passed' ? row.checks_passed !== row.checks_total : row.checks_passed === row.checks_total)
+                return null;
+        }
+        if (row.benchmark_eligibility === 'eligible' && (row.outcome !== 'passed' || receipt.instrumentation !== 'production'
+            || receipt.source_binding !== 'observed_endpoints' || receipt.build_identity !== row.recipe_sha256))
+            return null;
+        return structuredClone(row);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/agent/runtime/checked_commands.d.ts

@@ -0,0 +1,32 @@
+/** Explicit declared-process outcomes; never source or build qualification. */
+export interface CheckedCommandStage {
+    executable: string;
+    args: string[];
+    acceptable_exit_codes?: number[];
+}
+export interface CheckedCommandPlan {
+    steps: {
+        id: string;
+        pipeline: CheckedCommandStage[];
+    }[];
+}
+export interface CheckedCommandResult {
+    schema_version: 1;
+    status: 'passed' | 'failed' | 'incomplete' | 'timed_out' | 'cancelled';
+    verification: 'unknown';
+    plan_sha256: string;
+    steps: {
+        id: string;
+        status: 'passed' | 'failed' | 'skipped' | 'unknown';
+        stages: {
+            exit_code: number | null;
+            acceptable_exit_codes: number[];
+            accepted: boolean | null;
+        }[];
+    }[];
+    reason?: string;
+}
+/** Parse a bounded literal process plan; shell text is never inferred from its arguments. */
+export declare function parseCheckedCommandPlan(value: unknown): CheckedCommandPlan | null;
+/** Parse declared process outcomes without turning them into source or build qualification. */
+export declare function parseCheckedCommandResult(value: unknown): CheckedCommandResult | null;