@moretea-labs/forge 1.5.0-rc.1

package/src/runtime/execution/thin-harness/fast-receipt.ts

@@ -0,0 +1,235 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { createHash, randomUUID } from 'crypto';
+import { repositoryControllerRoot } from '../../../cli/repositories/controller-home';
+import {
+  FAST_RECEIPT_MAX_SUMMARY_BYTES,
+  FAST_RECEIPT_RETENTION,
+  type FastExecutionReceipt,
+  type FastOutcome,
+  type LatencyBreakdown,
+  type RuntimeObservability,
+} from './types';
+
+export interface CreateFastReceiptInput {
+  repoId: string;
+  checkoutId: string;
+  operation: string;
+  startedAt: string;
+  finishedAt?: string;
+  durationMs: number;
+  outcome: FastOutcome;
+  changedPaths?: string[];
+  repositoryChanged?: boolean;
+  authorizationDecision?: string;
+  policyDecision?: string;
+  outputSummary?: string;
+  artifactRefs?: string[];
+  latency?: LatencyBreakdown;
+  /** Internal measurement used for receipt observability even when latency detail is not returned. */
+  observabilityLatency?: LatencyBreakdown;
+  stepCount?: number;
+  laneCount?: number;
+  reasons?: string[];
+  executionId?: string;
+  requestId?: string;
+  fencingToken?: number;
+  baseHead?: string | null;
+  inputHash?: string;
+}
+
+function observabilityFor(input: CreateFastReceiptInput): RuntimeObservability {
+  const latency = input.observabilityLatency ?? input.latency;
+  const commandRuntimeMs = Math.max(0, latency?.executionMs ?? 0);
+  const controllerWaitMs = Math.max(0, latency?.schedulerWaitMs ?? 0);
+  return {
+    framework_overhead_ms: Math.max(0, Math.round((input.durationMs - commandRuntimeMs - controllerWaitMs) * 100) / 100),
+    command_runtime_ms: Math.round(commandRuntimeMs * 100) / 100,
+    controller_wait_ms: Math.round(controllerWaitMs * 100) / 100,
+    // A Fast receipt is the single durable command event for its executionId.
+    duplicate_event_count: 0,
+    automatic_retry_count: 0,
+    // Read operations do not refresh projections or write runtime state.
+    read_path_write_count: 0,
+  };
+}
+
+export interface WriteReceiptResult {
+  receipt?: FastExecutionReceipt;
+  persisted: boolean;
+  warning?: string;
+}
+
+function receiptsDir(controllerHome: string, repoId: string): string {
+  return join(repositoryControllerRoot(controllerHome, repoId), 'fast-receipts');
+}
+
+function receiptPath(controllerHome: string, repoId: string, executionId: string): string {
+  const safe = executionId.replace(/[^a-zA-Z0-9._-]+/g, '-').slice(0, 120);
+  return join(receiptsDir(controllerHome, repoId), `${safe}.json`);
+}
+
+function boundSummary(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  const bytes = Buffer.byteLength(value, 'utf8');
+  if (bytes <= FAST_RECEIPT_MAX_SUMMARY_BYTES) return value;
+  return `${value.slice(0, FAST_RECEIPT_MAX_SUMMARY_BYTES)}…[truncated ${bytes} bytes]`;
+}
+
+let pruneCounter = 0;
+
+/**
+ * Persist one bounded Fast Path receipt.
+ * Failures never throw to callers that already completed mutations.
+ */
+export function writeFastReceipt(controllerHome: string, input: CreateFastReceiptInput): WriteReceiptResult {
+  const executionId = input.executionId ?? `fast_${Date.now()}_${randomUUID().slice(0, 8)}`;
+  const finishedAt = input.finishedAt ?? new Date().toISOString();
+  const receipt: FastExecutionReceipt = {
+    schemaVersion: 1,
+    executionId,
+    repoId: input.repoId,
+    checkoutId: input.checkoutId,
+    mode: 'fast',
+    operation: input.operation,
+    startedAt: input.startedAt,
+    finishedAt,
+    durationMs: Math.max(0, Math.round(input.durationMs * 100) / 100),
+    outcome: input.outcome,
+    changedPaths: [...new Set(input.changedPaths ?? [])].slice(0, 200),
+    repositoryChanged: input.repositoryChanged === true,
+    authorizationDecision: input.authorizationDecision ?? 'session_or_policy',
+    policyDecision: input.policyDecision ?? 'allowed',
+    outputSummary: boundSummary(input.outputSummary),
+    artifactRefs: input.artifactRefs?.slice(0, 20),
+    latency: input.latency,
+    observability: observabilityFor(input),
+    stepCount: input.stepCount,
+    laneCount: input.laneCount,
+    reasons: input.reasons?.slice(0, 20),
+    requestId: input.requestId,
+    fencingToken: input.fencingToken,
+    baseHead: input.baseHead,
+    inputHash: input.inputHash,
+  };
+
+  try {
+    const dir = receiptsDir(controllerHome, input.repoId);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const target = receiptPath(controllerHome, input.repoId, executionId);
+    const temporary = `${target}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(receipt, null, 2)}\n`, 'utf8');
+    renameSync(temporary, target);
+    noteFastReceiptWritten();
+    pruneCounter += 1;
+    if (pruneCounter % 25 === 0) pruneFastReceipts(controllerHome, input.repoId);
+    return { receipt, persisted: true };
+  } catch (error) {
+    return {
+      receipt,
+      persisted: false,
+      warning: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export function readFastReceipt(
+  controllerHome: string,
+  repoId: string,
+  executionId: string,
+): FastExecutionReceipt | undefined {
+  const path = receiptPath(controllerHome, repoId, executionId);
+  if (!existsSync(path)) return undefined;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as FastExecutionReceipt;
+  } catch {
+    return undefined;
+  }
+}
+
+export function findFastReceiptByRequestId(
+  controllerHome: string,
+  repoId: string,
+  requestId: string,
+): FastExecutionReceipt | undefined {
+  if (!requestId.trim()) return undefined;
+  const list = listFastReceipts(controllerHome, repoId, FAST_RECEIPT_RETENTION);
+  return list.find((entry) => entry.requestId === requestId);
+}
+
+export function listFastReceipts(
+  controllerHome: string,
+  repoId: string,
+  limit = 20,
+): FastExecutionReceipt[] {
+  const dir = receiptsDir(controllerHome, repoId);
+  if (!existsSync(dir)) return [];
+  const files = readdirSync(dir)
+    .filter((name) => name.endsWith('.json'))
+    .map((name) => {
+      const path = join(dir, name);
+      try {
+        const receipt = JSON.parse(readFileSync(path, 'utf8')) as FastExecutionReceipt;
+        return { path, receipt, mtime: receipt.finishedAt ?? '' };
+      } catch {
+        return undefined;
+      }
+    })
+    .filter((entry): entry is { path: string; receipt: FastExecutionReceipt; mtime: string } => Boolean(entry))
+    .sort((left, right) => right.mtime.localeCompare(left.mtime));
+  return files.slice(0, Math.max(1, Math.min(limit, 100))).map((entry) => entry.receipt);
+}
+
+function pruneFastReceipts(controllerHome: string, repoId: string): void {
+  const dir = receiptsDir(controllerHome, repoId);
+  if (!existsSync(dir)) return;
+  const files = readdirSync(dir)
+    .filter((name) => name.endsWith('.json'))
+    .map((name) => join(dir, name))
+    .sort()
+    .reverse();
+  for (const path of files.slice(FAST_RECEIPT_RETENTION)) {
+    try {
+      rmSync(path, { force: true });
+    } catch {
+      /* best-effort */
+    }
+  }
+}
+
+export interface FastPathMetrics {
+  executionJobCount: number;
+  localJobCount: number;
+  workerSpawnCount: number;
+  projectionUpdateCount: number;
+  receiptCount: number;
+}
+
+const metrics: FastPathMetrics = {
+  executionJobCount: 0,
+  localJobCount: 0,
+  workerSpawnCount: 0,
+  projectionUpdateCount: 0,
+  receiptCount: 0,
+};
+
+export function resetFastPathMetrics(): void {
+  metrics.executionJobCount = 0;
+  metrics.localJobCount = 0;
+  metrics.workerSpawnCount = 0;
+  metrics.projectionUpdateCount = 0;
+  metrics.receiptCount = 0;
+  pruneCounter = 0;
+}
+
+export function noteFastReceiptWritten(): void {
+  metrics.receiptCount += 1;
+}
+
+export function getFastPathMetrics(): FastPathMetrics {
+  return { ...metrics };
+}
+
+export function hashRequestInput(value: unknown): string {
+  return createHash('sha256').update(JSON.stringify(value ?? null)).digest('hex').slice(0, 24);
+}

package/src/runtime/execution/thin-harness/fingerprint-worker.ts

@@ -0,0 +1,191 @@
+/**
+ * Worker-thread dirty path fingerprinting for Fast Path snapshots.
+ * Caps dirty file count, per-file bytes, total read bytes, and wall time.
+ * Exceeding budget throws SNAPSHOT_TOO_DIRTY / SNAPSHOT_BUDGET so callers escalate to Durable.
+ */
+import { createHash } from 'crypto';
+import { existsSync, lstatSync, readFileSync, readlinkSync } from 'fs';
+import { isMainThread, parentPort, workerData, Worker } from 'worker_threads';
+import { resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+export const MAX_DIRTY_PATHS_FOR_FINGERPRINT = 200;
+export const MAX_FINGERPRINT_FILE_BYTES = 256 * 1024;
+export const MAX_FINGERPRINT_TOTAL_BYTES = 8 * 1024 * 1024;
+export const MAX_FINGERPRINT_WORKER_MS = 5_000;
+
+export interface FingerprintJobInput {
+  root: string;
+  paths: string[];
+  statusByPath: Record<string, string[]>;
+  maxFileBytes?: number;
+  maxTotalBytes?: number;
+  maxPaths?: number;
+}
+
+export interface FingerprintJobResult {
+  pathFingerprints: Record<string, string>;
+  bytesRead: number;
+  pathCount: number;
+  timedOut?: boolean;
+  error?: string;
+}
+
+function fingerprintOne(
+  root: string,
+  relativePath: string,
+  statusLines: string[],
+  maxFileBytes: number,
+  budget: { total: number; maxTotal: number },
+): string {
+  const hash = createHash('sha256').update(statusLines.join('\n'));
+  const absolute = resolve(root, relativePath);
+  if (!existsSync(absolute)) return hash.update('\nmissing').digest('hex');
+  try {
+    const stat = lstatSync(absolute);
+    if (stat.isSymbolicLink()) {
+      hash.update(`\nsymlink:${readlinkSync(absolute)}`);
+    } else if (stat.isFile()) {
+      if (stat.size > maxFileBytes) {
+        hash.update(`\nlarge:${stat.size}:${stat.mode}`);
+      } else {
+        if (budget.total + stat.size > budget.maxTotal) {
+          throw new Error(
+            `SNAPSHOT_BUDGET: total fingerprint bytes would exceed ${budget.maxTotal}`,
+          );
+        }
+        const body = readFileSync(absolute);
+        budget.total += body.length;
+        hash.update('\nfile:').update(body);
+      }
+    } else {
+      hash.update(`\nmode:${stat.mode}:size:${stat.size}`);
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith('SNAPSHOT_BUDGET')) throw error;
+    hash.update(`\nunreadable:${error instanceof Error ? error.message : String(error)}`);
+  }
+  return hash.digest('hex');
+}
+
+export function computePathFingerprintsSync(input: FingerprintJobInput): FingerprintJobResult {
+  const maxPaths = input.maxPaths ?? MAX_DIRTY_PATHS_FOR_FINGERPRINT;
+  const maxFileBytes = input.maxFileBytes ?? MAX_FINGERPRINT_FILE_BYTES;
+  const maxTotal = input.maxTotalBytes ?? MAX_FINGERPRINT_TOTAL_BYTES;
+  if (input.paths.length > maxPaths) {
+    throw new Error(
+      `SNAPSHOT_TOO_DIRTY: ${input.paths.length} dirty paths exceeds Fast Path cap ${maxPaths}`,
+    );
+  }
+  const budget = { total: 0, maxTotal };
+  const pathFingerprints: Record<string, string> = {};
+  for (const path of input.paths) {
+    pathFingerprints[path] = fingerprintOne(
+      input.root,
+      path,
+      input.statusByPath[path] ?? [],
+      maxFileBytes,
+      budget,
+    );
+  }
+  return {
+    pathFingerprints,
+    bytesRead: budget.total,
+    pathCount: input.paths.length,
+  };
+}
+
+async function runInWorker(input: FingerprintJobInput, timeoutMs: number): Promise<FingerprintJobResult> {
+  const modulePath = fileURLToPath(import.meta.url);
+  return await new Promise<FingerprintJobResult>((resolvePromise, reject) => {
+    const worker = new Worker(modulePath, {
+      workerData: input,
+      // Bun / Node ESM worker entry
+      execArgv: [],
+    });
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      void worker.terminate().finally(() => {
+        reject(new Error(`SNAPSHOT_WORKER_TIMEOUT: fingerprint worker exceeded ${timeoutMs}ms`));
+      });
+    }, timeoutMs);
+    timer.unref?.();
+    worker.on('message', (message: FingerprintJobResult) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      void worker.terminate();
+      if (message.error) reject(new Error(message.error));
+      else resolvePromise(message);
+    });
+    worker.on('error', (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reject(error);
+    });
+    worker.on('exit', (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (code !== 0) {
+        reject(new Error(`SNAPSHOT_WORKER_EXIT: fingerprint worker exited ${code}`));
+      }
+    });
+  });
+}
+
+/**
+ * Compute dirty path fingerprints off the main event loop when possible.
+ * Falls back to sync on worker spawn failure (still bounded).
+ */
+export async function computePathFingerprintsAsync(
+  input: FingerprintJobInput,
+  options: { timeoutMs?: number; signal?: AbortSignal } = {},
+): Promise<FingerprintJobResult> {
+  if (options.signal?.aborted) {
+    throw new Error('CANCELLED: fingerprint aborted');
+  }
+  const timeoutMs = options.timeoutMs ?? MAX_FINGERPRINT_WORKER_MS;
+  // Empty / tiny jobs stay on main thread to avoid spawn overhead.
+  if (input.paths.length === 0) {
+    return { pathFingerprints: {}, bytesRead: 0, pathCount: 0 };
+  }
+  if (input.paths.length <= 2) {
+    return computePathFingerprintsSync(input);
+  }
+  try {
+    return await runInWorker(input, timeoutMs);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    // Timeouts / budget errors must not silently degrade to unbounded sync.
+    if (
+      message.startsWith('SNAPSHOT_WORKER_TIMEOUT')
+      || message.startsWith('SNAPSHOT_TOO_DIRTY')
+      || message.startsWith('SNAPSHOT_BUDGET')
+      || message.startsWith('CANCELLED')
+    ) {
+      throw error instanceof Error ? error : new Error(message);
+    }
+    // Worker spawn unavailable (some test runners): bounded sync fallback.
+    return computePathFingerprintsSync(input);
+  }
+}
+
+// Worker thread entry
+if (!isMainThread && parentPort) {
+  try {
+    const input = workerData as FingerprintJobInput;
+    const result = computePathFingerprintsSync(input);
+    parentPort.postMessage(result);
+  } catch (error) {
+    parentPort.postMessage({
+      pathFingerprints: {},
+      bytesRead: 0,
+      pathCount: 0,
+      error: error instanceof Error ? error.message : String(error),
+    } satisfies FingerprintJobResult);
+  }
+}

package/src/runtime/execution/thin-harness/index.ts

@@ -0,0 +1,13 @@
+export * from './types';
+export * from './latency-trace';
+export * from './execution-router';
+export * from './fast-receipt';
+export * from './fast-executor';
+export * from './batch-executor';
+export * from './lightweight-lanes';
+export * from './mutation-gate';
+export * from './async-process';
+export * from './request-ledger';
+export * from './proposal-store';
+export * from './workspace-savepoint';
+export * from './fingerprint-worker';

package/src/runtime/execution/thin-harness/latency-trace.ts

@@ -0,0 +1,107 @@
+import type { LatencyBreakdown } from './types';
+import { EMPTY_LATENCY } from './types';
+
+export type LatencySegment = 'routingMs' | 'policyMs' | 'snapshotMs' | 'executionMs' | 'receiptMs';
+
+const SEGMENT_KEYS: LatencySegment[] = [
+  'routingMs',
+  'policyMs',
+  'snapshotMs',
+  'executionMs',
+  'receiptMs',
+];
+
+function roundMs(value: number): number {
+  return Math.round(value * 100) / 100;
+}
+
+/**
+ * Bounded in-process latency accumulator with mutually exclusive segments.
+ */
+export class LatencyTrace {
+  private readonly startedAt = performance.now();
+  private readonly segments: Partial<Record<LatencySegment, number>> = {};
+  private active: { segment: LatencySegment; start: number } | undefined;
+  path: LatencyBreakdown['path'];
+
+  constructor(path?: LatencyBreakdown['path']) {
+    this.path = path;
+  }
+
+  start(segment: LatencySegment): void {
+    if (this.active) this.stop();
+    this.active = { segment, start: performance.now() };
+  }
+
+  stop(): void {
+    if (!this.active) return;
+    const elapsed = performance.now() - this.active.start;
+    this.segments[this.active.segment] = (this.segments[this.active.segment] ?? 0) + elapsed;
+    this.active = undefined;
+  }
+
+  add(segment: LatencySegment, ms: number): void {
+    if (!Number.isFinite(ms) || ms < 0) return;
+    this.segments[segment] = (this.segments[segment] ?? 0) + ms;
+  }
+
+  async measure<T>(segment: LatencySegment, operation: () => Promise<T>): Promise<T> {
+    this.start(segment);
+    try {
+      return await operation();
+    } finally {
+      this.stop();
+    }
+  }
+
+  measureSync<T>(segment: LatencySegment, operation: () => T): T {
+    this.start(segment);
+    try {
+      return operation();
+    } finally {
+      this.stop();
+    }
+  }
+
+  snapshot(includeDetail = true): LatencyBreakdown {
+    this.stop();
+    const totalMs = roundMs(performance.now() - this.startedAt);
+    const routingMs = roundMs(this.segments.routingMs ?? 0);
+    const policyMs = roundMs(this.segments.policyMs ?? 0);
+    const snapshotMs = roundMs(this.segments.snapshotMs ?? 0);
+    const executionMs = roundMs(this.segments.executionMs ?? 0);
+    const receiptMs = roundMs(this.segments.receiptMs ?? 0);
+    if (!includeDetail) {
+      return { ...EMPTY_LATENCY, totalMs, path: this.path };
+    }
+    return {
+      ...EMPTY_LATENCY,
+      routingMs,
+      policyMs,
+      snapshotMs,
+      executionMs,
+      receiptMs,
+      totalMs,
+      path: this.path,
+      // Compatibility aliases (non-overlapping mapping).
+      gatewayValidationMs: routingMs,
+      authorizationMs: policyMs,
+      repositorySnapshotMs: snapshotMs,
+      operationExecutionMs: executionMs,
+      evidencePersistenceMs: receiptMs,
+    };
+  }
+
+  summaryMs(): { totalMs: number; path?: LatencyBreakdown['path'] } {
+    this.stop();
+    return {
+      totalMs: roundMs(performance.now() - this.startedAt),
+      path: this.path,
+    };
+  }
+}
+
+export function harnessOverheadMs(breakdown: LatencyBreakdown): number {
+  const op = breakdown.executionMs || breakdown.operationExecutionMs || 0;
+  return Math.max(0, roundMs(breakdown.totalMs - op));
+}