@the-open-engine/zeroshot 6.39.2 → 6.41.0

package/cli/semantic-canonical.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalEvent = canonicalEvent;
+const semantic_json_1 = require("./semantic-json");
+const RESULT_OPTIONAL_KEYS = [
+    'result',
+    'error',
+    'cost',
+    'duration',
+    'inputTokens',
+    'outputTokens',
+    'cacheReadInputTokens',
+    'cacheCreationInputTokens',
+    'modelUsage',
+    'requests',
+    'usageSource',
+    'usageCompleteness',
+    'invocation',
+    'ompSdk',
+];
+function canonicalToolEvent(event) {
+    if (event.type === 'tool_call') {
+        return {
+            type: 'tool_call',
+            toolName: event.toolName ?? null,
+            toolId: event.toolId ?? null,
+            input: (0, semantic_json_1.normalizeUnknown)(event.input),
+        };
+    }
+    if (event.type !== 'tool_result')
+        return null;
+    return {
+        type: 'tool_result',
+        toolId: event.toolId ?? null,
+        content: (0, semantic_json_1.normalizeUnknown)(event.content),
+        isError: (0, semantic_json_1.normalizeUnknown)(event.isError),
+    };
+}
+function canonicalResult(event) {
+    if (event.type !== 'result' || typeof event.success !== 'boolean') {
+        throw new semantic_json_1.SemanticProjectionError('event_invalid');
+    }
+    const normalized = { type: 'result', success: event.success };
+    for (const key of RESULT_OPTIONAL_KEYS) {
+        if (event[key] !== undefined)
+            normalized[key] = (0, semantic_json_1.normalizeUnknown)(event[key]);
+    }
+    return normalized;
+}
+function canonicalEvent(event) {
+    if (!event || typeof event !== 'object' || typeof event.type !== 'string') {
+        throw new semantic_json_1.SemanticProjectionError('event_invalid');
+    }
+    if (event.type === 'text' || event.type === 'thinking') {
+        if (typeof event.text !== 'string')
+            throw new semantic_json_1.SemanticProjectionError('event_invalid');
+        return { type: event.type, text: (0, semantic_json_1.normalizeUnknown)(event.text) };
+    }
+    return canonicalToolEvent(event) ?? canonicalResult(event);
+}

package/cli/semantic-canonical.ts

@@ -0,0 +1,59 @@
+import type { OutputEvent } from './agent-provider-boundary';
+import { normalizeUnknown, SemanticProjectionError } from './semantic-json';
+
+const RESULT_OPTIONAL_KEYS = [
+  'result',
+  'error',
+  'cost',
+  'duration',
+  'inputTokens',
+  'outputTokens',
+  'cacheReadInputTokens',
+  'cacheCreationInputTokens',
+  'modelUsage',
+  'requests',
+  'usageSource',
+  'usageCompleteness',
+  'invocation',
+  'ompSdk',
+] as const;
+
+function canonicalToolEvent(event: OutputEvent): Record<string, unknown> | null {
+  if (event.type === 'tool_call') {
+    return {
+      type: 'tool_call',
+      toolName: event.toolName ?? null,
+      toolId: event.toolId ?? null,
+      input: normalizeUnknown(event.input),
+    };
+  }
+  if (event.type !== 'tool_result') return null;
+  return {
+    type: 'tool_result',
+    toolId: event.toolId ?? null,
+    content: normalizeUnknown(event.content),
+    isError: normalizeUnknown(event.isError),
+  };
+}
+
+function canonicalResult(event: OutputEvent): Record<string, unknown> {
+  if (event.type !== 'result' || typeof event.success !== 'boolean') {
+    throw new SemanticProjectionError('event_invalid');
+  }
+  const normalized: Record<string, unknown> = { type: 'result', success: event.success };
+  for (const key of RESULT_OPTIONAL_KEYS) {
+    if (event[key] !== undefined) normalized[key] = normalizeUnknown(event[key]);
+  }
+  return normalized;
+}
+
+export function canonicalEvent(event: OutputEvent): Record<string, unknown> {
+  if (!event || typeof event !== 'object' || typeof event.type !== 'string') {
+    throw new SemanticProjectionError('event_invalid');
+  }
+  if (event.type === 'text' || event.type === 'thinking') {
+    if (typeof event.text !== 'string') throw new SemanticProjectionError('event_invalid');
+    return { type: event.type, text: normalizeUnknown(event.text) };
+  }
+  return canonicalToolEvent(event) ?? canonicalResult(event);
+}

package/cli/semantic-contract.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SEMANTIC_BOUNDS = exports.MAX_DIAGNOSTICS_PER_TASK = exports.MAX_EVENTS_PER_TASK = exports.MAX_VALUE_NODES = exports.MAX_CONTAINER_ITEMS = exports.MAX_VALUE_DEPTH = exports.MAX_STRING_BYTES = exports.MAX_EVENT_BYTES = exports.MAX_LINE_BYTES = exports.SEMANTIC_MEDIA_TYPE = exports.SEMANTIC_SCHEMA_VERSION = void 0;
+exports.classifyOwnedLogLine = classifyOwnedLogLine;
+exports.reportDiagnostic = reportDiagnostic;
+const task_log_line_1 = require("../src/task-log-line");
+exports.SEMANTIC_SCHEMA_VERSION = 'zeroshot.semantic.v1';
+exports.SEMANTIC_MEDIA_TYPE = 'application/x-zeroshot-semantic+jsonl';
+exports.MAX_LINE_BYTES = 1024 * 1024;
+exports.MAX_EVENT_BYTES = 512 * 1024;
+exports.MAX_STRING_BYTES = 256 * 1024;
+exports.MAX_VALUE_DEPTH = 32;
+exports.MAX_CONTAINER_ITEMS = 4096;
+exports.MAX_VALUE_NODES = 16384;
+exports.MAX_EVENTS_PER_TASK = 100000;
+exports.MAX_DIAGNOSTICS_PER_TASK = 1000;
+exports.SEMANTIC_BOUNDS = {
+    maxLineBytes: exports.MAX_LINE_BYTES,
+    maxEventBytes: exports.MAX_EVENT_BYTES,
+    maxStringBytes: exports.MAX_STRING_BYTES,
+    maxValueDepth: exports.MAX_VALUE_DEPTH,
+    maxContainerItems: exports.MAX_CONTAINER_ITEMS,
+    maxValueNodes: exports.MAX_VALUE_NODES,
+    maxEventsPerTask: exports.MAX_EVENTS_PER_TASK,
+    maxDiagnosticsPerTask: exports.MAX_DIAGNOSTICS_PER_TASK,
+};
+const WRAPPER_LINE_PATTERNS = [
+    /^={50}$/,
+    /^Finished: \d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/,
+    /^Exit code: (?:-?\d+|null), Signal: (?:[A-Za-z0-9]+|null)$/,
+    /^Stop reason: [^,]+, Exit code: (?:-?\d+|null), Signal: (?:[A-Za-z0-9]+|null)$/,
+];
+function classifyOwnedLogLine(rawLine) {
+    const line = rawLine.trim();
+    if (!line)
+        return 'owned';
+    if (WRAPPER_LINE_PATTERNS.some((pattern) => pattern.test(line)))
+        return 'owned';
+    const decoded = (0, task_log_line_1.decodeTaskLogLine)(rawLine);
+    if (decoded.format === 'stderr-tagged-v1')
+        return 'format-v1';
+    if (decoded.format === 'channel-framed-v2')
+        return 'format-v2';
+    return decoded.providerOutput ? null : 'owned';
+}
+function diagnosticMessage(code) {
+    const messages = {
+        ambiguous_agent: 'Task evidence has more than one causal agent.',
+        event_invalid: 'Provider adapter emitted an invalid OutputEvent.',
+        event_limit_exceeded: 'Semantic event count exceeded the per-task bound.',
+        event_shape_too_deep: 'OutputEvent JSON exceeded the nesting bound.',
+        event_shape_too_large: 'OutputEvent JSON exceeded the node bound.',
+        event_shape_too_wide: 'OutputEvent JSON exceeded the container bound.',
+        event_string_too_large: 'OutputEvent string exceeded the byte bound.',
+        event_too_large: 'Canonical OutputEvent exceeded the byte bound.',
+        event_value_not_json: 'OutputEvent contained a non-JSON value.',
+        invalid_json_shape: 'Provider source line was not a JSON object.',
+        invalid_utf8: 'Provider source line was not valid UTF-8.',
+        legacy_ambiguous_channels: 'Legacy task log does not prove stdout and stderr provenance.',
+        line_too_large: 'Provider source line exceeded the byte bound.',
+        log_changed_during_parse: 'Raw provider output changed during semantic projection.',
+        log_changed_during_hash: 'Raw provider output changed while its digest was computed.',
+        log_missing: 'Raw provider output is missing.',
+        log_not_regular: 'Raw provider output is not a regular file.',
+        log_read_failed: 'Raw provider output could not be read completely.',
+        log_reference_invalid: 'Task raw-output reference is outside the owned log boundary.',
+        log_unreadable: 'Raw provider output could not be opened safely.',
+        malformed_json: 'Provider source line contained malformed JSON.',
+        output_after_terminal: 'Provider output followed the terminal result.',
+        parser_error: 'Provider adapter rejected a source line.',
+        parser_finish_error: 'Provider adapter failed while finishing its stateful parse.',
+        task_not_terminal: 'Task-store row was not terminal when evidence was captured.',
+        task_row_identity_mismatch: 'Task-store identity did not match causal ledger identity.',
+        task_row_missing: 'Causally referenced task-store row is missing.',
+        task_row_unreadable: 'Causally referenced task-store row could not be read.',
+        terminal_result_missing: 'Provider evidence did not produce one terminal result.',
+        unframed_log_line: 'A channel-framed task log contained an unframed source line.',
+        unknown_provider: 'Task provider has no registered Zeroshot adapter.',
+    };
+    return messages[code] || 'Semantic projection was incomplete.';
+}
+function reportDiagnostic(context, code, source) {
+    context.issueCodes.add(code);
+    if (context.diagnosticIndex >= exports.MAX_DIAGNOSTICS_PER_TASK) {
+        context.diagnosticsOmitted += 1;
+        return;
+    }
+    context.writer.write({
+        record_type: 'diagnostic',
+        task_id: context.taskId,
+        diagnostic_index: context.diagnosticIndex,
+        code,
+        message: diagnosticMessage(code),
+        source,
+    });
+    context.diagnosticIndex += 1;
+}

package/cli/semantic-contract.ts

@@ -0,0 +1,153 @@
+import type { ProviderAdapter } from './agent-provider-boundary';
+import type { ExportStream, RecordWriter } from './export-stream';
+import type { ClusterLedger } from './trace-evidence';
+import type fs = require('fs');
+import { decodeTaskLogLine } from '../src/task-log-line';
+
+export const SEMANTIC_SCHEMA_VERSION = 'zeroshot.semantic.v1';
+export const SEMANTIC_MEDIA_TYPE = 'application/x-zeroshot-semantic+jsonl';
+export const MAX_LINE_BYTES = 1024 * 1024;
+export const MAX_EVENT_BYTES = 512 * 1024;
+export const MAX_STRING_BYTES = 256 * 1024;
+export const MAX_VALUE_DEPTH = 32;
+export const MAX_CONTAINER_ITEMS = 4096;
+export const MAX_VALUE_NODES = 16384;
+export const MAX_EVENTS_PER_TASK = 100000;
+export const MAX_DIAGNOSTICS_PER_TASK = 1000;
+export const SEMANTIC_BOUNDS = {
+  maxLineBytes: MAX_LINE_BYTES,
+  maxEventBytes: MAX_EVENT_BYTES,
+  maxStringBytes: MAX_STRING_BYTES,
+  maxValueDepth: MAX_VALUE_DEPTH,
+  maxContainerItems: MAX_CONTAINER_ITEMS,
+  maxValueNodes: MAX_VALUE_NODES,
+  maxEventsPerTask: MAX_EVENTS_PER_TASK,
+  maxDiagnosticsPerTask: MAX_DIAGNOSTICS_PER_TASK,
+} as const;
+
+const WRAPPER_LINE_PATTERNS = [
+  /^={50}$/,
+  /^Finished: \d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/,
+  /^Exit code: (?:-?\d+|null), Signal: (?:[A-Za-z0-9]+|null)$/,
+  /^Stop reason: [^,]+, Exit code: (?:-?\d+|null), Signal: (?:[A-Za-z0-9]+|null)$/,
+] as const;
+export interface SemanticTask {
+  id?: unknown;
+  fullPrompt?: unknown;
+  prompt?: unknown;
+  status?: unknown;
+  provider?: unknown;
+  model?: unknown;
+  logFile?: unknown;
+}
+
+export interface SemanticExportOptions {
+  ledger: ClusterLedger;
+  clusterId: string;
+  readTask(taskId: string): SemanticTask | null;
+  allowedLogRoot: string;
+  outputPath?: string | null;
+  stdout?: ExportStream;
+}
+
+export interface SourceSpan {
+  line_number: number;
+  byte_start: number;
+  byte_end: number;
+  timestamp_ms: number | null;
+}
+
+export interface TaskProjection {
+  writer: RecordWriter;
+  taskId: string;
+  provider: string | null;
+  adapter: ProviderAdapter | null;
+  promptRef: string;
+  rawOutputRef: string;
+  rawOutputSha256: string | null;
+  eventIndex: number;
+  diagnosticIndex: number;
+  diagnosticsOmitted: number;
+  issueCodes: Set<string>;
+  logFormat: TaskLogFormat | null;
+  terminalResultEmitted: boolean;
+}
+
+export interface OpenedEvidence {
+  fd: number | null;
+  before: fs.BigIntStats | null;
+  byteLength: number | null;
+  sha256: string | null;
+  issue: string | null;
+}
+
+type TaskLogFormat = 'legacy-pi' | 'stderr-tagged-v1' | 'channel-framed-v2';
+export type OwnedLogLine = 'format-v1' | 'format-v2' | 'owned' | null;
+
+export function classifyOwnedLogLine(rawLine: string): OwnedLogLine {
+  const line = rawLine.trim();
+  if (!line) return 'owned';
+  if (WRAPPER_LINE_PATTERNS.some((pattern) => pattern.test(line))) return 'owned';
+  const decoded = decodeTaskLogLine(rawLine);
+  if (decoded.format === 'stderr-tagged-v1') return 'format-v1';
+  if (decoded.format === 'channel-framed-v2') return 'format-v2';
+  return decoded.providerOutput ? null : 'owned';
+}
+
+function diagnosticMessage(code: string): string {
+  const messages: Record<string, string> = {
+    ambiguous_agent: 'Task evidence has more than one causal agent.',
+    event_invalid: 'Provider adapter emitted an invalid OutputEvent.',
+    event_limit_exceeded: 'Semantic event count exceeded the per-task bound.',
+    event_shape_too_deep: 'OutputEvent JSON exceeded the nesting bound.',
+    event_shape_too_large: 'OutputEvent JSON exceeded the node bound.',
+    event_shape_too_wide: 'OutputEvent JSON exceeded the container bound.',
+    event_string_too_large: 'OutputEvent string exceeded the byte bound.',
+    event_too_large: 'Canonical OutputEvent exceeded the byte bound.',
+    event_value_not_json: 'OutputEvent contained a non-JSON value.',
+    invalid_json_shape: 'Provider source line was not a JSON object.',
+    invalid_utf8: 'Provider source line was not valid UTF-8.',
+    legacy_ambiguous_channels: 'Legacy task log does not prove stdout and stderr provenance.',
+    line_too_large: 'Provider source line exceeded the byte bound.',
+    log_changed_during_parse: 'Raw provider output changed during semantic projection.',
+    log_changed_during_hash: 'Raw provider output changed while its digest was computed.',
+    log_missing: 'Raw provider output is missing.',
+    log_not_regular: 'Raw provider output is not a regular file.',
+    log_read_failed: 'Raw provider output could not be read completely.',
+    log_reference_invalid: 'Task raw-output reference is outside the owned log boundary.',
+    log_unreadable: 'Raw provider output could not be opened safely.',
+    malformed_json: 'Provider source line contained malformed JSON.',
+    output_after_terminal: 'Provider output followed the terminal result.',
+    parser_error: 'Provider adapter rejected a source line.',
+    parser_finish_error: 'Provider adapter failed while finishing its stateful parse.',
+    task_not_terminal: 'Task-store row was not terminal when evidence was captured.',
+    task_row_identity_mismatch: 'Task-store identity did not match causal ledger identity.',
+    task_row_missing: 'Causally referenced task-store row is missing.',
+    task_row_unreadable: 'Causally referenced task-store row could not be read.',
+    terminal_result_missing: 'Provider evidence did not produce one terminal result.',
+    unframed_log_line: 'A channel-framed task log contained an unframed source line.',
+    unknown_provider: 'Task provider has no registered Zeroshot adapter.',
+  };
+  return messages[code] || 'Semantic projection was incomplete.';
+}
+
+export function reportDiagnostic(
+  context: TaskProjection,
+  code: string,
+  source: SourceSpan | null
+): void {
+  context.issueCodes.add(code);
+  if (context.diagnosticIndex >= MAX_DIAGNOSTICS_PER_TASK) {
+    context.diagnosticsOmitted += 1;
+    return;
+  }
+  context.writer.write({
+    record_type: 'diagnostic',
+    task_id: context.taskId,
+    diagnostic_index: context.diagnosticIndex,
+    code,
+    message: diagnosticMessage(code),
+    source,
+  });
+  context.diagnosticIndex += 1;
+}

package/cli/semantic-events.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitEvent = emitEvent;
+exports.emittedEvents = emittedEvents;
+const semantic_canonical_1 = require("./semantic-canonical");
+const semantic_contract_1 = require("./semantic-contract");
+const semantic_json_1 = require("./semantic-json");
+function emitEvent(context, event, source, derivation) {
+    if (context.terminalResultEmitted) {
+        (0, semantic_contract_1.reportDiagnostic)(context, 'output_after_terminal', source);
+        return;
+    }
+    if (context.eventIndex >= semantic_contract_1.MAX_EVENTS_PER_TASK) {
+        if (!context.issueCodes.has('event_limit_exceeded')) {
+            (0, semantic_contract_1.reportDiagnostic)(context, 'event_limit_exceeded', source);
+        }
+        return;
+    }
+    try {
+        const normalized = (0, semantic_canonical_1.canonicalEvent)(event);
+        if (Buffer.byteLength(JSON.stringify(normalized)) > semantic_contract_1.MAX_EVENT_BYTES) {
+            throw new semantic_json_1.SemanticProjectionError('event_too_large');
+        }
+        context.writer.write({
+            record_type: 'event',
+            task_id: context.taskId,
+            event_index: context.eventIndex,
+            provider: context.provider,
+            adapter_id: context.adapter?.id ?? null,
+            adapter_version: context.adapter?.adapterVersion ?? null,
+            prompt_ref: context.promptRef,
+            raw_output_ref: context.rawOutputRef,
+            raw_output_sha256: context.rawOutputSha256,
+            derivation,
+            source,
+            event: normalized,
+        });
+        context.eventIndex += 1;
+        if (normalized.type === 'result')
+            context.terminalResultEmitted = true;
+    }
+    catch (error) {
+        (0, semantic_contract_1.reportDiagnostic)(context, error instanceof semantic_json_1.SemanticProjectionError ? error.code : 'event_invalid', source);
+    }
+}
+function emittedEvents(result) {
+    if (result === null)
+        return [];
+    return isEventArray(result) ? result : [result];
+}
+function isEventArray(result) {
+    return Array.isArray(result);
+}

package/cli/semantic-events.ts

@@ -0,0 +1,65 @@
+import type { OutputEvent, ProviderParseResult } from './agent-provider-boundary';
+import { canonicalEvent } from './semantic-canonical';
+import {
+  MAX_EVENTS_PER_TASK,
+  MAX_EVENT_BYTES,
+  reportDiagnostic,
+  type SourceSpan,
+  type TaskProjection,
+} from './semantic-contract';
+import { SemanticProjectionError } from './semantic-json';
+
+export function emitEvent(
+  context: TaskProjection,
+  event: OutputEvent,
+  source: SourceSpan | null,
+  derivation: 'line' | 'finish'
+): void {
+  if (context.terminalResultEmitted) {
+    reportDiagnostic(context, 'output_after_terminal', source);
+    return;
+  }
+  if (context.eventIndex >= MAX_EVENTS_PER_TASK) {
+    if (!context.issueCodes.has('event_limit_exceeded')) {
+      reportDiagnostic(context, 'event_limit_exceeded', source);
+    }
+    return;
+  }
+  try {
+    const normalized = canonicalEvent(event);
+    if (Buffer.byteLength(JSON.stringify(normalized)) > MAX_EVENT_BYTES) {
+      throw new SemanticProjectionError('event_too_large');
+    }
+    context.writer.write({
+      record_type: 'event',
+      task_id: context.taskId,
+      event_index: context.eventIndex,
+      provider: context.provider,
+      adapter_id: context.adapter?.id ?? null,
+      adapter_version: context.adapter?.adapterVersion ?? null,
+      prompt_ref: context.promptRef,
+      raw_output_ref: context.rawOutputRef,
+      raw_output_sha256: context.rawOutputSha256,
+      derivation,
+      source,
+      event: normalized,
+    });
+    context.eventIndex += 1;
+    if (normalized.type === 'result') context.terminalResultEmitted = true;
+  } catch (error) {
+    reportDiagnostic(
+      context,
+      error instanceof SemanticProjectionError ? error.code : 'event_invalid',
+      source
+    );
+  }
+}
+
+export function emittedEvents(result: ProviderParseResult): readonly OutputEvent[] {
+  if (result === null) return [];
+  return isEventArray(result) ? result : [result];
+}
+
+function isEventArray(result: ProviderParseResult): result is readonly OutputEvent[] {
+  return Array.isArray(result);
+}

package/cli/semantic-evidence.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openEvidence = openEvidence;
+exports.emptyEvidence = emptyEvidence;
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+const export_stream_1 = require("./export-stream");
+const trace_evidence_1 = require("./trace-evidence");
+const trace_output_1 = require("./trace-output");
+function hashOpenedEvidence(fd, byteLength) {
+    const digest = crypto.createHash('sha256');
+    let bytes = 0;
+    while (bytes < byteLength) {
+        const buffer = Buffer.allocUnsafe(Math.min(trace_output_1.TRACE_OUTPUT_CHUNK_BYTES, byteLength - bytes));
+        const read = fs.readSync(fd, buffer, 0, buffer.length, bytes);
+        if (read === 0)
+            break;
+        digest.update(read === buffer.length ? buffer : buffer.subarray(0, read));
+        bytes += read;
+    }
+    return { bytes, sha256: digest.digest('hex') };
+}
+function unavailable(issue) {
+    return { fd: null, before: null, byteLength: null, sha256: null, issue };
+}
+function openEvidence(taskId, task, allowedLogRoot) {
+    const expected = (0, trace_evidence_1.expectedLogPath)(allowedLogRoot, taskId);
+    const recorded = (0, export_stream_1.nullableString)(task.logFile);
+    if (!expected || !recorded || path.resolve(recorded) !== expected) {
+        return unavailable('log_reference_invalid');
+    }
+    let fd;
+    try {
+        fd = fs.openSync(expected, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+    }
+    catch (error) {
+        const code = typeof error === 'object' && error !== null && 'code' in error ? error.code : null;
+        return unavailable(code === 'ENOENT' ? 'log_missing' : 'log_unreadable');
+    }
+    try {
+        const before = fs.fstatSync(fd, { bigint: true });
+        if (!before.isFile() || before.size > BigInt(Number.MAX_SAFE_INTEGER)) {
+            fs.closeSync(fd);
+            return unavailable('log_not_regular');
+        }
+        const byteLength = Number(before.size);
+        const hashed = hashOpenedEvidence(fd, byteLength);
+        const afterHash = fs.fstatSync(fd, { bigint: true });
+        if (hashed.bytes !== byteLength || !(0, export_stream_1.sameFileSnapshot)(before, afterHash)) {
+            fs.closeSync(fd);
+            return { ...unavailable('log_changed_during_hash'), byteLength };
+        }
+        return { fd, before, byteLength, sha256: hashed.sha256, issue: null };
+    }
+    catch {
+        fs.closeSync(fd);
+        return unavailable('log_read_failed');
+    }
+}
+function emptyEvidence() {
+    return { fd: null, before: null, byteLength: null, sha256: null, issue: null };
+}

package/cli/semantic-evidence.ts

@@ -0,0 +1,65 @@
+import crypto = require('crypto');
+import fs = require('fs');
+import path = require('path');
+import { nullableString, sameFileSnapshot } from './export-stream';
+import type { OpenedEvidence, SemanticTask } from './semantic-contract';
+import { expectedLogPath } from './trace-evidence';
+import { TRACE_OUTPUT_CHUNK_BYTES } from './trace-output';
+
+function hashOpenedEvidence(fd: number, byteLength: number): { bytes: number; sha256: string } {
+  const digest = crypto.createHash('sha256');
+  let bytes = 0;
+  while (bytes < byteLength) {
+    const buffer = Buffer.allocUnsafe(Math.min(TRACE_OUTPUT_CHUNK_BYTES, byteLength - bytes));
+    const read = fs.readSync(fd, buffer, 0, buffer.length, bytes);
+    if (read === 0) break;
+    digest.update(read === buffer.length ? buffer : buffer.subarray(0, read));
+    bytes += read;
+  }
+  return { bytes, sha256: digest.digest('hex') };
+}
+
+function unavailable(issue: string): OpenedEvidence {
+  return { fd: null, before: null, byteLength: null, sha256: null, issue };
+}
+
+export function openEvidence(
+  taskId: string,
+  task: SemanticTask,
+  allowedLogRoot: string
+): OpenedEvidence {
+  const expected = expectedLogPath(allowedLogRoot, taskId);
+  const recorded = nullableString(task.logFile);
+  if (!expected || !recorded || path.resolve(recorded) !== expected) {
+    return unavailable('log_reference_invalid');
+  }
+  let fd: number;
+  try {
+    fd = fs.openSync(expected, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+  } catch (error) {
+    const code = typeof error === 'object' && error !== null && 'code' in error ? error.code : null;
+    return unavailable(code === 'ENOENT' ? 'log_missing' : 'log_unreadable');
+  }
+  try {
+    const before = fs.fstatSync(fd, { bigint: true });
+    if (!before.isFile() || before.size > BigInt(Number.MAX_SAFE_INTEGER)) {
+      fs.closeSync(fd);
+      return unavailable('log_not_regular');
+    }
+    const byteLength = Number(before.size);
+    const hashed = hashOpenedEvidence(fd, byteLength);
+    const afterHash = fs.fstatSync(fd, { bigint: true });
+    if (hashed.bytes !== byteLength || !sameFileSnapshot(before, afterHash)) {
+      fs.closeSync(fd);
+      return { ...unavailable('log_changed_during_hash'), byteLength };
+    }
+    return { fd, before, byteLength, sha256: hashed.sha256, issue: null };
+  } catch {
+    fs.closeSync(fd);
+    return unavailable('log_read_failed');
+  }
+}
+
+export function emptyEvidence(): OpenedEvidence {
+  return { fd: null, before: null, byteLength: null, sha256: null, issue: null };
+}