@probelabs/probe 0.6.0-rc331 → 0.6.0-rc332

package/build/agent/governance/acknowledgedJsonlChannel.js

@@ -0,0 +1,328 @@
+/**
+ * Acknowledged JSONL channel exposed by the package governance subpath.
+ *
+ * Semantics are derived from the accepted ReqProof EXP-0171 cooperative
+ * channel at commit dcc888120cfbeb04f8bfe59147f272c2396723e0. This is the
+ * reusable channel primitive only, not a port of that experiment's runner.
+ */
+
+import { PassThrough } from 'stream';
+
+const DEFAULT_FRAME_BYTE_CAP = 256;
+const DEFAULT_TOTAL_BYTE_CAP = 1024;
+const DEFAULT_IDLE_TIMEOUT_MS = 50;
+const DEFAULT_DEADLINE_MS = 400;
+const DEFAULT_HIGH_WATER_MARK = 16 * 1024;
+
+function positiveInteger(value, fallback, name) {
+  if (value === undefined) return fallback;
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new TypeError(`${name} must be a positive safe integer`);
+  }
+  return value;
+}
+
+function nonNegativeNumber(value, fallback, name) {
+  if (value === undefined) return fallback;
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+    throw new TypeError(`${name} must be a non-negative finite number`);
+  }
+  return value;
+}
+
+export function createAcknowledgedJsonlChannel(options = {}) {
+  if (typeof options.onRecord !== 'function') {
+    throw new TypeError('onRecord must be a function');
+  }
+
+  const frameByteCap = positiveInteger(options.frameByteCap, DEFAULT_FRAME_BYTE_CAP, 'frameByteCap');
+  const totalByteCap = positiveInteger(options.totalByteCap, DEFAULT_TOTAL_BYTE_CAP, 'totalByteCap');
+  const idleTimeoutMs = nonNegativeNumber(options.idleTimeoutMs, DEFAULT_IDLE_TIMEOUT_MS, 'idleTimeoutMs');
+  const deadlineMs = nonNegativeNumber(options.deadlineMs, DEFAULT_DEADLINE_MS, 'deadlineMs');
+  const highWaterMark = positiveInteger(options.highWaterMark, DEFAULT_HIGH_WATER_MARK, 'highWaterMark');
+
+  const stream = new PassThrough({ highWaterMark });
+  const controller = new AbortController();
+  const pendingAcks = new Set();
+  const pendingWrites = new Set();
+  const timers = new Set();
+  let partial = Buffer.alloc(0);
+  let totalBytes = 0;
+  let frames = 0;
+  let acknowledgements = 0;
+  let accepting = true;
+  let eof = false;
+  let settled = false;
+  let cleaned = false;
+  let cleanupPromise = null;
+  let failure = null;
+  let firstFailureCount = 0;
+  let laterFailureCount = 0;
+  let abortCount = 0;
+  let backpressureCount = 0;
+  let drainWaiters = 0;
+  let idleTimer = null;
+  let deadlineTimer = null;
+  let resolveResult;
+
+  const result = new Promise(resolve => { resolveResult = resolve; });
+  const closed = new Promise(resolve => stream.once('close', resolve));
+
+  const clearOwnedTimer = timer => {
+    if (!timer) return;
+    clearTimeout(timer);
+    timers.delete(timer);
+  };
+
+  const ownedTimer = (delay, callback) => {
+    if (delay === 0) return null;
+    const timer = setTimeout(() => {
+      timers.delete(timer);
+      callback();
+    }, delay);
+    timers.add(timer);
+    return timer;
+  };
+
+  const clearTimers = () => {
+    clearOwnedTimer(idleTimer);
+    clearOwnedTimer(deadlineTimer);
+    idleTimer = null;
+    deadlineTimer = null;
+  };
+
+  const settle = classification => {
+    if (settled) return;
+    settled = true;
+    accepting = false;
+    clearTimers();
+    resolveResult(Object.freeze({
+      classification,
+      error: failure?.message ?? null,
+      frames,
+      acknowledgements,
+      eof
+    }));
+  };
+
+  const fail = (classification, error) => {
+    if (failure) {
+      laterFailureCount += 1;
+      return false;
+    }
+    failure = {
+      classification,
+      message: error instanceof Error ? error.message : String(error ?? classification)
+    };
+    firstFailureCount += 1;
+    abortCount += 1;
+    accepting = false;
+    controller.abort(failure);
+    settle(classification);
+    return true;
+  };
+
+  const maybePass = () => {
+    if (eof && pendingAcks.size === 0 && !failure) settle('PASS');
+  };
+
+  const touchIdle = () => {
+    clearOwnedTimer(idleTimer);
+    idleTimer = ownedTimer(idleTimeoutMs, () => fail('FAIL_IDLE_TIMEOUT'));
+  };
+
+  const observeAck = value => {
+    const underlying = Promise.resolve(value);
+    let active = true;
+    let resolveOwned;
+    const owned = new Promise(resolve => { resolveOwned = resolve; });
+    const finish = acknowledged => {
+      if (!active) return;
+      active = false;
+      controller.signal.removeEventListener('abort', onAbort);
+      if (acknowledged) acknowledgements += 1;
+      resolveOwned();
+    };
+    const onAbort = () => finish(false);
+
+    pendingAcks.add(owned);
+    controller.signal.addEventListener('abort', onAbort, { once: true });
+    underlying.then(
+      () => finish(true),
+      error => {
+        fail('FAIL_ACK', error);
+        finish(false);
+      }
+    );
+    if (controller.signal.aborted) onAbort();
+    owned.then(() => {
+      pendingAcks.delete(owned);
+      maybePass();
+    });
+  };
+
+  const acceptFrame = bytes => {
+    let record;
+    try {
+      record = JSON.parse(bytes.toString('utf8'));
+    } catch (error) {
+      fail('FAIL_PARSE', error);
+      return;
+    }
+    const keys = record && typeof record === 'object' ? Object.keys(record) : [];
+    if (keys.join(',') !== 'id,value' ||
+        !Number.isSafeInteger(record.id) || record.id < 0 || typeof record.value !== 'string' ||
+        !bytes.equals(Buffer.from(JSON.stringify(record), 'utf8'))) {
+      fail('FAIL_PARSE', 'frame is not canonical JSON');
+      return;
+    }
+    frames += 1;
+    try {
+      observeAck(options.onRecord(record, controller.signal));
+    } catch (error) {
+      fail('FAIL_ACK', error);
+    }
+  };
+
+  const ingest = chunk => {
+    if (!accepting) return;
+    const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    let offset = 0;
+    while (offset < bytes.length && accepting) {
+      const newline = bytes.indexOf(10, offset);
+      const end = newline === -1 ? bytes.length : newline;
+      const segment = bytes.subarray(offset, end);
+      if (partial.length + segment.length > frameByteCap) {
+        fail('FAIL_FRAME_CAP');
+        return;
+      }
+      if (segment.length > 0) partial = Buffer.concat([partial, segment]);
+      if (newline === -1) break;
+      const frame = partial;
+      partial = Buffer.alloc(0);
+      acceptFrame(frame);
+      offset = newline + 1;
+    }
+    if (accepting) touchIdle();
+  };
+
+  const onData = chunk => {
+    try { ingest(chunk); } catch (error) { fail('FAIL_SOURCE', error); }
+  };
+  const onEnd = () => {
+    eof = true;
+    clearOwnedTimer(idleTimer);
+    idleTimer = null;
+    if (partial.length > 0) fail('FAIL_PARTIAL_EOF');
+    else maybePass();
+  };
+  const onError = error => fail('FAIL_SOURCE', error);
+
+  stream.on('data', onData);
+  stream.once('end', onEnd);
+  stream.on('error', onError);
+  touchIdle();
+  deadlineTimer = ownedTimer(deadlineMs, () => fail('FAIL_DEADLINE'));
+
+  const trackWrite = operation => {
+    pendingWrites.add(operation);
+    operation.finally(() => pendingWrites.delete(operation));
+    return operation;
+  };
+
+  const write = input => {
+    if (!accepting) return Promise.resolve(false);
+    let byteLength;
+    if (Buffer.isBuffer(input) || input instanceof Uint8Array) byteLength = input.byteLength;
+    else if (typeof input === 'string') byteLength = Buffer.byteLength(input);
+    else throw new TypeError('write input must be a Buffer, string, or Uint8Array');
+    if (totalBytes + byteLength > totalByteCap) {
+      fail('FAIL_TOTAL_CAP');
+      return Promise.resolve(false);
+    }
+    const bytes = Buffer.from(input);
+    totalBytes += byteLength;
+    let resolveCallback;
+    const callbackDone = new Promise(resolve => { resolveCallback = resolve; });
+    let resolveDrain = () => {};
+    let drained = null;
+
+    stream.cork();
+    const accepted = stream.write(bytes, error => {
+      if (error) fail('FAIL_SOURCE', error);
+      resolveCallback();
+    });
+    if (!accepted) {
+      backpressureCount += 1;
+      drainWaiters += 1;
+      drained = new Promise(resolve => {
+        resolveDrain = () => {
+          stream.off('drain', onDrain);
+          controller.signal.removeEventListener('abort', onAbort);
+          drainWaiters -= 1;
+          resolve();
+        };
+        const onDrain = () => resolveDrain();
+        const onAbort = () => resolveDrain();
+        stream.once('drain', onDrain);
+        controller.signal.addEventListener('abort', onAbort, { once: true });
+      });
+    }
+    queueMicrotask(() => stream.uncork());
+
+    return trackWrite(Promise.all([callbackDone, drained ?? Promise.resolve()])
+      .then(() => accepting || eof));
+  };
+
+  const end = () => {
+    if (stream.writableEnded || stream.destroyed) return Promise.resolve();
+    let resolveEnd;
+    const operation = new Promise(resolve => { resolveEnd = resolve; });
+    pendingWrites.add(operation);
+    stream.end(() => resolveEnd());
+    operation.finally(() => pendingWrites.delete(operation));
+    return operation;
+  };
+
+  const snapshot = () => Object.freeze({
+    accepting,
+    eof,
+    frames,
+    acknowledgements,
+    totalBytes,
+    partialBytes: partial.length,
+    pending: pendingAcks.size,
+    writes: pendingWrites.size,
+    timers: timers.size,
+    drainWaiters,
+    backpressureCount,
+    firstFailureCount,
+    laterFailureCount,
+    abortCount,
+    listeners: ['data', 'end', 'error', 'close', 'drain']
+      .reduce((count, event) => count + stream.listenerCount(event), 0)
+  });
+
+  const cleanup = () => {
+    if (cleanupPromise) return cleanupPromise;
+    cleanupPromise = (async () => {
+      clearTimers();
+      if (pendingAcks.size > 0 && !failure) fail('FAIL_CLEANUP');
+      if (!stream.writableEnded && !stream.destroyed) {
+        if (failure) stream.destroy();
+        else await end();
+      }
+      await Promise.allSettled([...pendingWrites]);
+      await Promise.allSettled([...pendingAcks]);
+      if (!stream.destroyed) stream.destroy();
+      await closed;
+      stream.off('data', onData);
+      stream.off('end', onEnd);
+      stream.off('error', onError);
+      cleaned = true;
+    })();
+    return cleanupPromise;
+  };
+
+  return Object.freeze({ write, end, result, cleanup, snapshot: () => ({ ...snapshot(), cleaned }) });
+}

package/build/agent/governance/atomicTerminalReceipt.js

@@ -0,0 +1,188 @@
+/**
+ * Guarded atomic terminal-receipt writer exposed by the package governance subpath.
+ *
+ * Semantics are derived from the accepted ReqProof EXP-0164 finalizer at
+ * source commit dc1a80476c89699e4d9a4921b6ef5d7f980a3c60. The caller owns a
+ * unique attempt directory and a single writer.
+ * Publication is process-observed atomicity, not power-loss durability for the
+ * directory entry: this narrow primitive intentionally does not fsync the directory.
+ */
+
+import { constants } from 'fs';
+import { lstat, open, readFile, realpath, rename, unlink } from 'fs/promises';
+import { basename, dirname, join, resolve } from 'path';
+
+const DEFAULT_NAME = 'receipt.json';
+const DEFAULT_MAX_BYTES = 16_384;
+const CLEANUP_ATTEMPTS = 3;
+
+function safeName(name) {
+  return typeof name === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) &&
+    Buffer.byteLength(name) <= 255 && basename(name) === name;
+}
+
+async function absent(path) {
+  try {
+    return { absent: false, info: await lstat(path) };
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { absent: true, info: null };
+    throw error;
+  }
+}
+
+async function guardDirectory(directory) {
+  if (typeof directory !== 'string' || directory !== resolve(directory)) {
+    throw new TypeError('directory must be an absolute canonical path');
+  }
+  const info = await lstat(directory);
+  if (!info.isDirectory() || info.isSymbolicLink() || await realpath(directory) !== directory) {
+    throw new Error('directory must be an existing canonical nonsymlink directory');
+  }
+}
+
+function guardChild(path, directory, expectedName) {
+  if (dirname(path) !== directory || basename(path) !== expectedName) {
+    throw new Error('receipt path must be an exact immediate child');
+  }
+}
+
+async function requireAbsent(path, label) {
+  const observed = await absent(path);
+  if (!observed.absent) {
+    const kind = observed.info.isSymbolicLink() ? 'symlink' : 'occupied path';
+    throw new Error(`${label} ${kind} is forbidden`);
+  }
+}
+
+function combinedFailure(primary, cleanupErrors, cleanupComplete) {
+  if (cleanupErrors.length === 0) return primary;
+  const error = new AggregateError(
+    [primary, ...cleanupErrors],
+    cleanupComplete
+      ? 'receipt operation failed after cleanup recovery'
+      : 'receipt operation and owned cleanup failed',
+    { cause: primary }
+  );
+  Object.defineProperties(error, {
+    primary: { value: primary, enumerable: true },
+    cleanupErrors: { value: Object.freeze([...cleanupErrors]), enumerable: true },
+    cleanupComplete: { value: cleanupComplete, enumerable: true }
+  });
+  return error;
+}
+
+function measuredBytes(bytes) {
+  if (Buffer.isBuffer(bytes) || bytes instanceof Uint8Array) return bytes.byteLength;
+  if (typeof bytes === 'string') return Buffer.byteLength(bytes);
+  throw new TypeError('bytes must be a Buffer, string, or Uint8Array');
+}
+
+export async function writeAtomicTerminalReceipt({
+  directory,
+  name = DEFAULT_NAME,
+  bytes,
+  maxBytes = DEFAULT_MAX_BYTES
+} = {}) {
+  if (!safeName(name) || !safeName(`${name}.tmp`)) {
+    throw new TypeError('name must be a safe basename');
+  }
+  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+    throw new TypeError('maxBytes must be a positive safe integer');
+  }
+  const byteLength = measuredBytes(bytes);
+  if (byteLength > maxBytes) throw new Error('receipt exceeds maxBytes');
+
+  await guardDirectory(directory);
+  const finalPath = join(directory, name);
+  const temporaryPath = join(directory, `${name}.tmp`);
+  guardChild(finalPath, directory, name);
+  guardChild(temporaryPath, directory, `${name}.tmp`);
+  await requireAbsent(finalPath, 'final receipt');
+  await requireAbsent(temporaryPath, 'temporary receipt');
+
+  const payload = Buffer.from(bytes);
+  let handle;
+  let createdTemporary = false;
+  let renamed = false;
+  let result;
+  let primary;
+  try {
+    handle = await open(
+      temporaryPath,
+      constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL,
+      0o600
+    );
+    createdTemporary = true;
+    let offset = 0;
+    while (offset < payload.length) {
+      const { bytesWritten } = await handle.write(payload, offset, payload.length - offset, offset);
+      if (bytesWritten <= 0) throw new Error('receipt write made no progress');
+      offset += bytesWritten;
+    }
+    await handle.sync();
+    await handle.chmod(0o600);
+    await handle.close();
+    handle = undefined;
+
+    await guardDirectory(directory);
+    await requireAbsent(finalPath, 'final receipt');
+    const temporary = await lstat(temporaryPath);
+    if (!temporary.isFile() || temporary.isSymbolicLink() ||
+        (temporary.mode & 0o777) !== 0o600 || temporary.size !== byteLength) {
+      throw new Error('temporary receipt failed guarded validation');
+    }
+    await rename(temporaryPath, finalPath);
+    renamed = true;
+
+    const info = await lstat(finalPath);
+    const actual = await readFile(finalPath);
+    if (!info.isFile() || info.isSymbolicLink() || (info.mode & 0o777) !== 0o600 ||
+        info.size !== byteLength || actual.length !== byteLength || !actual.equals(payload)) {
+      throw new Error('published receipt failed exact validation');
+    }
+    result = Object.freeze({ bytes: actual, mode: info.mode & 0o777, size: info.size });
+  } catch (error) {
+    primary = error;
+  }
+
+  if (primary) {
+    const cleanupErrors = [];
+    let cleanupComplete = false;
+    let temporaryAbsent = !createdTemporary || renamed;
+    for (let attempt = 1; attempt <= CLEANUP_ATTEMPTS && !cleanupComplete; attempt += 1) {
+      if (handle) {
+        try {
+          await handle.close();
+          handle = undefined;
+        } catch (error) {
+          cleanupErrors.push(error);
+        }
+      }
+      if (!handle && createdTemporary && !renamed) {
+        try {
+          await guardDirectory(directory);
+          guardChild(temporaryPath, directory, `${name}.tmp`);
+          const temporary = await absent(temporaryPath);
+          if (!temporary.absent) {
+            if (!temporary.info.isFile() || temporary.info.isSymbolicLink()) {
+              throw new Error('owned temporary receipt changed type during cleanup');
+            }
+            await unlink(temporaryPath);
+          }
+          if (!(await absent(temporaryPath)).absent) {
+            throw new Error('owned temporary receipt remains after cleanup');
+          }
+          temporaryAbsent = true;
+        } catch (error) {
+          cleanupErrors.push(error);
+          temporaryAbsent = false;
+        }
+      }
+      cleanupComplete = !handle && temporaryAbsent;
+    }
+    if (!cleanupComplete) cleanupErrors.push(new Error('owned receipt cleanup remained incomplete'));
+    throw combinedFailure(primary, cleanupErrors, cleanupComplete);
+  }
+
+  return result;
+}

package/build/agent/governance/index.d.ts

@@ -0,0 +1,130 @@
+/// <reference types="node" />
+
+export type GovernedSignalScope = 'child' | 'process-group';
+export type GovernedProcessClassification =
+  | 'exited'
+  | 'terminated'
+  | 'aborted'
+  | 'execution_timeout'
+  | 'output_overflow'
+  | 'cleanup_timeout'
+  | 'spawn_error';
+
+export interface GovernedProcessSpec {
+  command: string;
+  args?: string[];
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  signal?: AbortSignal;
+  executionTimeoutMs?: number;
+  terminationGraceMs?: number;
+  cleanupTimeoutMs?: number;
+  stdoutByteCap?: number;
+  stderrByteCap?: number;
+  signalScope?: GovernedSignalScope;
+}
+
+export interface GovernedProcessBarrierState {
+  close: boolean;
+  stdoutEOF: boolean;
+  stderrEOF: boolean;
+}
+
+export interface GovernedProcessObservation {
+  sequence: number;
+  fact: string;
+  [detail: string]: unknown;
+}
+
+export interface GovernedProcessReceipt {
+  id: string;
+  classification: GovernedProcessClassification;
+  reason: string | null;
+  error?: string;
+  stdout: string;
+  stderr: string;
+  stdoutBytes: number;
+  stderrBytes: number;
+  exitCode: number | null;
+  signal: NodeJS.Signals | null;
+  barriers: Readonly<GovernedProcessBarrierState>;
+  observed: readonly Readonly<GovernedProcessObservation>[];
+}
+
+export interface GovernedProcessHandle {
+  readonly id: string;
+  terminate(reason?: string): Promise<GovernedProcessReceipt>;
+  readonly result: Promise<GovernedProcessReceipt>;
+}
+
+export function spawnGovernedProcess(spec: GovernedProcessSpec): GovernedProcessHandle;
+
+export interface AcknowledgedJsonlRecord {
+  id: number;
+  value: string;
+}
+
+export interface AcknowledgedJsonlChannelOptions {
+  onRecord(record: AcknowledgedJsonlRecord, signal: AbortSignal): unknown | PromiseLike<unknown>;
+  frameByteCap?: number;
+  totalByteCap?: number;
+  idleTimeoutMs?: number;
+  deadlineMs?: number;
+  highWaterMark?: number;
+}
+
+export interface AcknowledgedJsonlChannelResult {
+  classification: string;
+  error: string | null;
+  frames: number;
+  acknowledgements: number;
+  eof: boolean;
+}
+
+export interface AcknowledgedJsonlChannelSnapshot {
+  accepting: boolean;
+  eof: boolean;
+  frames: number;
+  acknowledgements: number;
+  totalBytes: number;
+  partialBytes: number;
+  pending: number;
+  writes: number;
+  timers: number;
+  drainWaiters: number;
+  backpressureCount: number;
+  firstFailureCount: number;
+  laterFailureCount: number;
+  abortCount: number;
+  listeners: number;
+  cleaned: boolean;
+}
+
+export interface AcknowledgedJsonlChannel {
+  write(input: Buffer | Uint8Array | string): Promise<boolean>;
+  end(): Promise<void>;
+  readonly result: Promise<Readonly<AcknowledgedJsonlChannelResult>>;
+  cleanup(): Promise<void>;
+  snapshot(): AcknowledgedJsonlChannelSnapshot;
+}
+
+export function createAcknowledgedJsonlChannel(
+  options: AcknowledgedJsonlChannelOptions
+): Readonly<AcknowledgedJsonlChannel>;
+
+export interface AtomicTerminalReceiptOptions {
+  directory: string;
+  name?: string;
+  bytes: Buffer | Uint8Array | string;
+  maxBytes?: number;
+}
+
+export interface AtomicTerminalReceiptResult {
+  bytes: Buffer;
+  mode: number;
+  size: number;
+}
+
+export function writeAtomicTerminalReceipt(
+  options: AtomicTerminalReceiptOptions
+): Promise<Readonly<AtomicTerminalReceiptResult>>;

package/build/agent/governance/index.js

@@ -0,0 +1,8 @@
+/**
+ * Public ESM entry point for Probe's accepted process-governance primitives.
+ * This module deliberately has no dependency on the package root or dotenv.
+ */
+
+export { spawnGovernedProcess } from '../processSupervisor.js';
+export { createAcknowledgedJsonlChannel } from './acknowledgedJsonlChannel.js';
+export { writeAtomicTerminalReceipt } from './atomicTerminalReceipt.js';