@the-open-engine/zeroshot 6.39.1 → 6.40.0

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 };
+}

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>() });
+}