@the-open-engine/zeroshot 6.39.2 → 6.40.0

package/cli/semantic-export.js

@@ -0,0 +1,186 @@
+"use strict";
+const fs = require("fs");
+const path = require("path");
+const agent_provider_boundary_1 = require("./agent-provider-boundary");
+const export_stream_1 = require("./export-stream");
+const semantic_contract_1 = require("./semantic-contract");
+const semantic_evidence_1 = require("./semantic-evidence");
+const semantic_parser_1 = require("./semantic-parser");
+const trace_evidence_1 = require("./trace-evidence");
+const trace_output_1 = require("./trace-output");
+function assertOutputIsNotTaskLog(outputPath, allowedLogRoot, taskIds) {
+    if (!outputPath)
+        return;
+    const resolvedOutput = path.resolve(outputPath);
+    for (const taskId of taskIds) {
+        if ((0, trace_evidence_1.expectedLogPath)(allowedLogRoot, taskId) === resolvedOutput) {
+            throw new Error('Semantic export output cannot replace a source task log');
+        }
+    }
+}
+function resolveAdapter(provider) {
+    if (!provider)
+        return null;
+    try {
+        return (0, agent_provider_boundary_1.getProviderAdapter)(provider);
+    }
+    catch {
+        return null;
+    }
+}
+function taskPrompt(task) {
+    if (!task)
+        return null;
+    return (0, export_stream_1.nullableString)(task.fullPrompt) ?? (0, export_stream_1.nullableString)(task.prompt);
+}
+function writeTaskRecord(options) {
+    const { writer, taskId, agentId, task, adapter, evidence } = options;
+    writer.write({
+        record_type: 'task',
+        task_id: taskId,
+        agent_id: agentId,
+        provider: (0, export_stream_1.nullableString)(task?.provider),
+        adapter_id: adapter?.id ?? null,
+        adapter_version: adapter?.adapterVersion ?? null,
+        model: (0, export_stream_1.nullableString)(task?.model),
+        prompt_ref: (0, trace_evidence_1.logicalTaskRef)(taskId, 'prompt'),
+        prompt: taskPrompt(task),
+        raw_output_ref: (0, trace_evidence_1.logicalTaskRef)(taskId, 'output'),
+        raw_output_sha256: evidence.sha256,
+        raw_output_byte_length: evidence.byteLength,
+    });
+}
+function createTaskProjection(writer, taskId, provider, adapter, evidence) {
+    return {
+        writer,
+        taskId,
+        provider,
+        adapter,
+        promptRef: (0, trace_evidence_1.logicalTaskRef)(taskId, 'prompt'),
+        rawOutputRef: (0, trace_evidence_1.logicalTaskRef)(taskId, 'output'),
+        rawOutputSha256: evidence.sha256,
+        eventIndex: 0,
+        diagnosticIndex: 0,
+        diagnosticsOmitted: 0,
+        issueCodes: new Set(),
+        logFormat: provider === 'pi' ? 'legacy-pi' : null,
+        terminalResultEmitted: false,
+    };
+}
+function reportInitialIssues(context, options) {
+    if (options.agentIds.length > 1)
+        (0, semantic_contract_1.reportDiagnostic)(context, 'ambiguous_agent', null);
+    if (options.taskIssue) {
+        (0, semantic_contract_1.reportDiagnostic)(context, options.taskIssue.split(':').at(-1) || 'task_row_unreadable', null);
+    }
+    if (options.taskPresent && !options.taskTerminal) {
+        (0, semantic_contract_1.reportDiagnostic)(context, 'task_not_terminal', null);
+    }
+    if (options.evidenceIssue)
+        (0, semantic_contract_1.reportDiagnostic)(context, options.evidenceIssue, null);
+    if (options.taskPresent && !context.adapter)
+        (0, semantic_contract_1.reportDiagnostic)(context, 'unknown_provider', null);
+}
+function streamSemanticTask(options) {
+    const { writer, taskId, cause, readTask, allowedLogRoot, footerIssues } = options;
+    const taskRead = (0, trace_evidence_1.readTraceTask)(taskId, readTask);
+    const task = taskRead.task;
+    const provider = (0, export_stream_1.nullableString)(task?.provider);
+    const adapter = resolveAdapter(provider);
+    const evidence = task ? (0, semantic_evidence_1.openEvidence)(taskId, task, allowedLogRoot) : (0, semantic_evidence_1.emptyEvidence)();
+    const agentIds = [...cause.agentIds].sort(export_stream_1.compareText);
+    const taskTerminal = task !== null && (0, trace_evidence_1.hasTerminalTaskStatus)(task);
+    writeTaskRecord({
+        writer,
+        taskId,
+        agentId: agentIds.length === 1 ? (agentIds[0] ?? null) : null,
+        task,
+        adapter,
+        evidence,
+    });
+    const context = createTaskProjection(writer, taskId, provider, adapter, evidence);
+    reportInitialIssues(context, {
+        agentIds,
+        taskIssue: taskRead.issue,
+        taskPresent: task !== null,
+        taskTerminal,
+        evidenceIssue: evidence.issue,
+    });
+    let sourceStable = evidence.issue === null && evidence.fd !== null;
+    if (sourceStable && adapter)
+        sourceStable = (0, semantic_parser_1.parseOpenedEvidence)(evidence, context, adapter);
+    if (evidence.fd !== null)
+        fs.closeSync(evidence.fd);
+    const sourceComplete = sourceStable && taskTerminal;
+    const semanticComplete = sourceComplete && adapter !== null && context.issueCodes.size === 0;
+    for (const code of context.issueCodes)
+        footerIssues.push(`task:${taskId}:${code}`);
+    writer.write({
+        record_type: 'task_end',
+        task_id: taskId,
+        source_complete: sourceComplete,
+        semantic_complete: semanticComplete,
+        events: context.eventIndex,
+        diagnostics: context.diagnosticIndex,
+        diagnostics_omitted: context.diagnosticsOmitted,
+    });
+    return { events: context.eventIndex, diagnostics: context.diagnosticIndex };
+}
+function streamClusterSemanticExport(options) {
+    const { ledger, clusterId, readTask, allowedLogRoot, outputPath = null } = options;
+    const causes = (0, trace_evidence_1.collectTaskCauses)(ledger, clusterId);
+    assertOutputIsNotTaskLog(outputPath, allowedLogRoot, causes.keys());
+    const destination = (0, export_stream_1.createExclusiveDestination)(outputPath, options.stdout ?? process.stdout, 'Semantic');
+    const writer = (0, export_stream_1.createRecordWriter)(destination);
+    const footerIssues = [];
+    let events = 0;
+    let diagnostics = 0;
+    try {
+        writer.write({
+            record_type: 'header',
+            schema_version: semantic_contract_1.SEMANTIC_SCHEMA_VERSION,
+            media_type: semantic_contract_1.SEMANTIC_MEDIA_TYPE,
+            cluster_id: clusterId,
+            bounds: {
+                read_chunk_bytes: trace_output_1.TRACE_OUTPUT_CHUNK_BYTES,
+                max_line_bytes: semantic_contract_1.SEMANTIC_BOUNDS.maxLineBytes,
+                max_event_bytes: semantic_contract_1.SEMANTIC_BOUNDS.maxEventBytes,
+                max_string_bytes: semantic_contract_1.SEMANTIC_BOUNDS.maxStringBytes,
+                max_value_depth: semantic_contract_1.SEMANTIC_BOUNDS.maxValueDepth,
+                max_container_items: semantic_contract_1.SEMANTIC_BOUNDS.maxContainerItems,
+                max_value_nodes: semantic_contract_1.SEMANTIC_BOUNDS.maxValueNodes,
+                max_events_per_task: semantic_contract_1.SEMANTIC_BOUNDS.maxEventsPerTask,
+                max_diagnostics_per_task: semantic_contract_1.SEMANTIC_BOUNDS.maxDiagnosticsPerTask,
+            },
+        });
+        const ordered = [...causes.entries()].sort(([left], [right]) => (0, export_stream_1.compareText)(left, right));
+        for (const [taskId, cause] of ordered) {
+            const summary = streamSemanticTask({
+                writer,
+                taskId,
+                cause,
+                readTask,
+                allowedLogRoot,
+                footerIssues,
+            });
+            events += summary.events;
+            diagnostics += summary.diagnostics;
+        }
+        footerIssues.sort(export_stream_1.compareText);
+        writer.finish({
+            record_type: 'footer',
+            complete: footerIssues.length === 0,
+            tasks: causes.size,
+            events,
+            diagnostics,
+            issues: footerIssues,
+        });
+    }
+    finally {
+        destination.close();
+    }
+}
+module.exports = {
+    SEMANTIC_EXPORT_BOUNDS: semantic_contract_1.SEMANTIC_BOUNDS,
+    streamClusterSemanticExport,
+};

package/cli/semantic-export.ts

@@ -0,0 +1,245 @@
+import fs = require('fs');
+import path = require('path');
+import { getProviderAdapter, type ProviderAdapter } from './agent-provider-boundary';
+import {
+  compareText,
+  createExclusiveDestination,
+  createRecordWriter,
+  nullableString,
+  type RecordWriter,
+} from './export-stream';
+import {
+  reportDiagnostic,
+  SEMANTIC_BOUNDS,
+  SEMANTIC_MEDIA_TYPE,
+  SEMANTIC_SCHEMA_VERSION,
+  type OpenedEvidence,
+  type SemanticExportOptions,
+  type SemanticTask,
+  type TaskProjection,
+} from './semantic-contract';
+import { emptyEvidence, openEvidence } from './semantic-evidence';
+import { parseOpenedEvidence } from './semantic-parser';
+import {
+  collectTaskCauses,
+  expectedLogPath,
+  hasTerminalTaskStatus,
+  logicalTaskRef,
+  readTraceTask,
+  type TaskCause,
+} from './trace-evidence';
+import { TRACE_OUTPUT_CHUNK_BYTES } from './trace-output';
+
+interface StreamTaskOptions {
+  writer: RecordWriter;
+  taskId: string;
+  cause: TaskCause;
+  readTask: SemanticExportOptions['readTask'];
+  allowedLogRoot: string;
+  footerIssues: string[];
+}
+
+interface TaskRecordOptions {
+  writer: RecordWriter;
+  taskId: string;
+  agentId: string | null;
+  task: SemanticTask | null;
+  adapter: ProviderAdapter | null;
+  evidence: OpenedEvidence;
+}
+
+interface InitialIssueOptions {
+  agentIds: readonly string[];
+  taskIssue: string | null;
+  taskPresent: boolean;
+  taskTerminal: boolean;
+  evidenceIssue: string | null;
+}
+
+function assertOutputIsNotTaskLog(
+  outputPath: string | null | undefined,
+  allowedLogRoot: string,
+  taskIds: Iterable<string>
+): void {
+  if (!outputPath) return;
+  const resolvedOutput = path.resolve(outputPath);
+  for (const taskId of taskIds) {
+    if (expectedLogPath(allowedLogRoot, taskId) === resolvedOutput) {
+      throw new Error('Semantic export output cannot replace a source task log');
+    }
+  }
+}
+
+function resolveAdapter(provider: string | null): ProviderAdapter | null {
+  if (!provider) return null;
+  try {
+    return getProviderAdapter(provider);
+  } catch {
+    return null;
+  }
+}
+
+function taskPrompt(task: SemanticTask | null): string | null {
+  if (!task) return null;
+  return nullableString(task.fullPrompt) ?? nullableString(task.prompt);
+}
+
+function writeTaskRecord(options: TaskRecordOptions): void {
+  const { writer, taskId, agentId, task, adapter, evidence } = options;
+  writer.write({
+    record_type: 'task',
+    task_id: taskId,
+    agent_id: agentId,
+    provider: nullableString(task?.provider),
+    adapter_id: adapter?.id ?? null,
+    adapter_version: adapter?.adapterVersion ?? null,
+    model: nullableString(task?.model),
+    prompt_ref: logicalTaskRef(taskId, 'prompt'),
+    prompt: taskPrompt(task),
+    raw_output_ref: logicalTaskRef(taskId, 'output'),
+    raw_output_sha256: evidence.sha256,
+    raw_output_byte_length: evidence.byteLength,
+  });
+}
+
+function createTaskProjection(
+  writer: RecordWriter,
+  taskId: string,
+  provider: string | null,
+  adapter: ProviderAdapter | null,
+  evidence: OpenedEvidence
+): TaskProjection {
+  return {
+    writer,
+    taskId,
+    provider,
+    adapter,
+    promptRef: logicalTaskRef(taskId, 'prompt'),
+    rawOutputRef: logicalTaskRef(taskId, 'output'),
+    rawOutputSha256: evidence.sha256,
+    eventIndex: 0,
+    diagnosticIndex: 0,
+    diagnosticsOmitted: 0,
+    issueCodes: new Set<string>(),
+    logFormat: provider === 'pi' ? 'legacy-pi' : null,
+    terminalResultEmitted: false,
+  };
+}
+
+function reportInitialIssues(context: TaskProjection, options: InitialIssueOptions): void {
+  if (options.agentIds.length > 1) reportDiagnostic(context, 'ambiguous_agent', null);
+  if (options.taskIssue) {
+    reportDiagnostic(context, options.taskIssue.split(':').at(-1) || 'task_row_unreadable', null);
+  }
+  if (options.taskPresent && !options.taskTerminal) {
+    reportDiagnostic(context, 'task_not_terminal', null);
+  }
+  if (options.evidenceIssue) reportDiagnostic(context, options.evidenceIssue, null);
+  if (options.taskPresent && !context.adapter) reportDiagnostic(context, 'unknown_provider', null);
+}
+
+function streamSemanticTask(options: StreamTaskOptions): { events: number; diagnostics: number } {
+  const { writer, taskId, cause, readTask, allowedLogRoot, footerIssues } = options;
+  const taskRead = readTraceTask(taskId, readTask);
+  const task = taskRead.task as SemanticTask | null;
+  const provider = nullableString(task?.provider);
+  const adapter = resolveAdapter(provider);
+  const evidence = task ? openEvidence(taskId, task, allowedLogRoot) : emptyEvidence();
+  const agentIds = [...cause.agentIds].sort(compareText);
+  const taskTerminal = task !== null && hasTerminalTaskStatus(task);
+  writeTaskRecord({
+    writer,
+    taskId,
+    agentId: agentIds.length === 1 ? (agentIds[0] ?? null) : null,
+    task,
+    adapter,
+    evidence,
+  });
+  const context = createTaskProjection(writer, taskId, provider, adapter, evidence);
+  reportInitialIssues(context, {
+    agentIds,
+    taskIssue: taskRead.issue,
+    taskPresent: task !== null,
+    taskTerminal,
+    evidenceIssue: evidence.issue,
+  });
+  let sourceStable = evidence.issue === null && evidence.fd !== null;
+  if (sourceStable && adapter) sourceStable = parseOpenedEvidence(evidence, context, adapter);
+  if (evidence.fd !== null) fs.closeSync(evidence.fd);
+  const sourceComplete = sourceStable && taskTerminal;
+  const semanticComplete = sourceComplete && adapter !== null && context.issueCodes.size === 0;
+  for (const code of context.issueCodes) footerIssues.push(`task:${taskId}:${code}`);
+  writer.write({
+    record_type: 'task_end',
+    task_id: taskId,
+    source_complete: sourceComplete,
+    semantic_complete: semanticComplete,
+    events: context.eventIndex,
+    diagnostics: context.diagnosticIndex,
+    diagnostics_omitted: context.diagnosticsOmitted,
+  });
+  return { events: context.eventIndex, diagnostics: context.diagnosticIndex };
+}
+
+function streamClusterSemanticExport(options: SemanticExportOptions): void {
+  const { ledger, clusterId, readTask, allowedLogRoot, outputPath = null } = options;
+  const causes = collectTaskCauses(ledger, clusterId);
+  assertOutputIsNotTaskLog(outputPath, allowedLogRoot, causes.keys());
+  const destination = createExclusiveDestination(
+    outputPath,
+    options.stdout ?? process.stdout,
+    'Semantic'
+  );
+  const writer = createRecordWriter(destination);
+  const footerIssues: string[] = [];
+  let events = 0;
+  let diagnostics = 0;
+  try {
+    writer.write({
+      record_type: 'header',
+      schema_version: SEMANTIC_SCHEMA_VERSION,
+      media_type: SEMANTIC_MEDIA_TYPE,
+      cluster_id: clusterId,
+      bounds: {
+        read_chunk_bytes: TRACE_OUTPUT_CHUNK_BYTES,
+        max_line_bytes: SEMANTIC_BOUNDS.maxLineBytes,
+        max_event_bytes: SEMANTIC_BOUNDS.maxEventBytes,
+        max_string_bytes: SEMANTIC_BOUNDS.maxStringBytes,
+        max_value_depth: SEMANTIC_BOUNDS.maxValueDepth,
+        max_container_items: SEMANTIC_BOUNDS.maxContainerItems,
+        max_value_nodes: SEMANTIC_BOUNDS.maxValueNodes,
+        max_events_per_task: SEMANTIC_BOUNDS.maxEventsPerTask,
+        max_diagnostics_per_task: SEMANTIC_BOUNDS.maxDiagnosticsPerTask,
+      },
+    });
+    const ordered = [...causes.entries()].sort(([left], [right]) => compareText(left, right));
+    for (const [taskId, cause] of ordered) {
+      const summary = streamSemanticTask({
+        writer,
+        taskId,
+        cause,
+        readTask,
+        allowedLogRoot,
+        footerIssues,
+      });
+      events += summary.events;
+      diagnostics += summary.diagnostics;
+    }
+    footerIssues.sort(compareText);
+    writer.finish({
+      record_type: 'footer',
+      complete: footerIssues.length === 0,
+      tasks: causes.size,
+      events,
+      diagnostics,
+      issues: footerIssues,
+    });
+  } finally {
+    destination.close();
+  }
+}
+
+export = {
+  SEMANTIC_EXPORT_BOUNDS: SEMANTIC_BOUNDS,
+  streamClusterSemanticExport,
+};

package/cli/semantic-json.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SemanticProjectionError = void 0;
+exports.normalizeUnknown = normalizeUnknown;
+const export_stream_1 = require("./export-stream");
+const semantic_contract_1 = require("./semantic-contract");
+class SemanticProjectionError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+exports.SemanticProjectionError = SemanticProjectionError;
+function isPlainRecord(value) {
+    const prototype = Reflect.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function normalizeJsonValue(value, depth, budget) {
+    budget.nodes += 1;
+    if (budget.nodes > semantic_contract_1.MAX_VALUE_NODES)
+        throw new SemanticProjectionError('event_shape_too_large');
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'string') {
+        if (Buffer.byteLength(value) > semantic_contract_1.MAX_STRING_BYTES) {
+            throw new SemanticProjectionError('event_string_too_large');
+        }
+        return value;
+    }
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new SemanticProjectionError('event_value_not_json');
+        return Object.is(value, -0) ? 0 : value;
+    }
+    if (typeof value !== 'object')
+        throw new SemanticProjectionError('event_value_not_json');
+    if (depth >= semantic_contract_1.MAX_VALUE_DEPTH)
+        throw new SemanticProjectionError('event_shape_too_deep');
+    if (budget.seen.has(value))
+        throw new SemanticProjectionError('event_value_not_json');
+    budget.seen.add(value);
+    try {
+        if (Array.isArray(value)) {
+            if (value.length > semantic_contract_1.MAX_CONTAINER_ITEMS) {
+                throw new SemanticProjectionError('event_shape_too_wide');
+            }
+            return value.map((item) => normalizeJsonValue(item, depth + 1, budget));
+        }
+        if (!isPlainRecord(value))
+            throw new SemanticProjectionError('event_value_not_json');
+        const keys = Object.keys(value).sort(export_stream_1.compareText);
+        if (keys.length > semantic_contract_1.MAX_CONTAINER_ITEMS) {
+            throw new SemanticProjectionError('event_shape_too_wide');
+        }
+        const normalized = {};
+        for (const key of keys)
+            normalized[key] = normalizeJsonValue(value[key], depth + 1, budget);
+        return normalized;
+    }
+    finally {
+        budget.seen.delete(value);
+    }
+}
+function normalizeUnknown(value) {
+    return normalizeJsonValue(value, 0, { nodes: 0, seen: new WeakSet() });
+}

package/cli/semantic-json.ts

@@ -0,0 +1,69 @@
+import { compareText } from './export-stream';
+import {
+  MAX_CONTAINER_ITEMS,
+  MAX_STRING_BYTES,
+  MAX_VALUE_DEPTH,
+  MAX_VALUE_NODES,
+} from './semantic-contract';
+
+interface JsonBudget {
+  nodes: number;
+  seen: WeakSet<object>;
+}
+
+export class SemanticProjectionError extends Error {
+  readonly code: string;
+
+  constructor(code: string) {
+    super(code);
+    this.code = code;
+  }
+}
+
+function isPlainRecord(value: object): value is Record<string, unknown> {
+  const prototype: object | null = Reflect.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function normalizeJsonValue(value: unknown, depth: number, budget: JsonBudget): unknown {
+  budget.nodes += 1;
+  if (budget.nodes > MAX_VALUE_NODES) throw new SemanticProjectionError('event_shape_too_large');
+  if (value === null || value === undefined) return null;
+  if (typeof value === 'string') {
+    if (Buffer.byteLength(value) > MAX_STRING_BYTES) {
+      throw new SemanticProjectionError('event_string_too_large');
+    }
+    return value;
+  }
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new SemanticProjectionError('event_value_not_json');
+    return Object.is(value, -0) ? 0 : value;
+  }
+  if (typeof value !== 'object') throw new SemanticProjectionError('event_value_not_json');
+  if (depth >= MAX_VALUE_DEPTH) throw new SemanticProjectionError('event_shape_too_deep');
+  if (budget.seen.has(value)) throw new SemanticProjectionError('event_value_not_json');
+  budget.seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      if (value.length > MAX_CONTAINER_ITEMS) {
+        throw new SemanticProjectionError('event_shape_too_wide');
+      }
+      return value.map((item) => normalizeJsonValue(item, depth + 1, budget));
+    }
+    if (!isPlainRecord(value)) throw new SemanticProjectionError('event_value_not_json');
+    const keys = Object.keys(value).sort(compareText);
+    if (keys.length > MAX_CONTAINER_ITEMS) {
+      throw new SemanticProjectionError('event_shape_too_wide');
+    }
+    const normalized: Record<string, unknown> = {};
+    for (const key of keys) normalized[key] = normalizeJsonValue(value[key], depth + 1, budget);
+    return normalized;
+  } finally {
+    budget.seen.delete(value);
+  }
+}
+
+export function normalizeUnknown(value: unknown): unknown {
+  return normalizeJsonValue(value, 0, { nodes: 0, seen: new WeakSet<object>() });
+}

package/cli/semantic-line-scanner.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BoundedLineScanner = void 0;
+const semantic_contract_1 = require("./semantic-contract");
+class BoundedLineScanner {
+    consumeLine;
+    parts = [];
+    lineBytes = 0;
+    lineStart = 0;
+    lineNumber = 1;
+    oversized = false;
+    constructor(consumeLine) {
+        this.consumeLine = consumeLine;
+    }
+    consume(chunk, absoluteStart) {
+        let offset = 0;
+        while (offset < chunk.length) {
+            const newline = chunk.indexOf(0x0a, offset);
+            const end = newline === -1 ? chunk.length : newline;
+            this.append(chunk.subarray(offset, end));
+            if (newline === -1)
+                return;
+            this.flush(absoluteStart + newline);
+            offset = newline + 1;
+        }
+    }
+    finish(byteLength) {
+        if (this.lineBytes > 0 || this.oversized)
+            this.flush(byteLength);
+    }
+    append(part) {
+        this.lineBytes += part.length;
+        if (this.lineBytes > semantic_contract_1.MAX_LINE_BYTES) {
+            this.oversized = true;
+            this.parts.length = 0;
+            return;
+        }
+        if (!this.oversized && part.length > 0)
+            this.parts.push(part);
+    }
+    flush(byteEnd) {
+        const source = {
+            line_number: this.lineNumber,
+            byte_start: this.lineStart,
+            byte_end: byteEnd,
+            timestamp_ms: null,
+        };
+        this.consumeLine(this.oversized ? null : Buffer.concat(this.parts, this.lineBytes), source);
+        this.parts.length = 0;
+        this.lineBytes = 0;
+        this.lineStart = byteEnd + 1;
+        this.lineNumber += 1;
+        this.oversized = false;
+    }
+}
+exports.BoundedLineScanner = BoundedLineScanner;

package/cli/semantic-line-scanner.ts

@@ -0,0 +1,54 @@
+import { MAX_LINE_BYTES, type SourceSpan } from './semantic-contract';
+
+type LineConsumer = (line: Buffer | null, source: SourceSpan) => void;
+
+export class BoundedLineScanner {
+  private readonly parts: Buffer[] = [];
+  private lineBytes = 0;
+  private lineStart = 0;
+  private lineNumber = 1;
+  private oversized = false;
+
+  constructor(private readonly consumeLine: LineConsumer) {}
+
+  consume(chunk: Buffer, absoluteStart: number): void {
+    let offset = 0;
+    while (offset < chunk.length) {
+      const newline = chunk.indexOf(0x0a, offset);
+      const end = newline === -1 ? chunk.length : newline;
+      this.append(chunk.subarray(offset, end));
+      if (newline === -1) return;
+      this.flush(absoluteStart + newline);
+      offset = newline + 1;
+    }
+  }
+
+  finish(byteLength: number): void {
+    if (this.lineBytes > 0 || this.oversized) this.flush(byteLength);
+  }
+
+  private append(part: Buffer): void {
+    this.lineBytes += part.length;
+    if (this.lineBytes > MAX_LINE_BYTES) {
+      this.oversized = true;
+      this.parts.length = 0;
+      return;
+    }
+    if (!this.oversized && part.length > 0) this.parts.push(part);
+  }
+
+  private flush(byteEnd: number): void {
+    const source: SourceSpan = {
+      line_number: this.lineNumber,
+      byte_start: this.lineStart,
+      byte_end: byteEnd,
+      timestamp_ms: null,
+    };
+    this.consumeLine(this.oversized ? null : Buffer.concat(this.parts, this.lineBytes), source);
+    this.parts.length = 0;
+    this.lineBytes = 0;
+    this.lineStart = byteEnd + 1;
+    this.lineNumber += 1;
+    this.oversized = false;
+  }
+}