engineering-behavior-observatory 0.2.1

package/dist/src/process-protocol.js

@@ -0,0 +1,1261 @@
+import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { closeSync, constants, fsyncSync, mkdirSync, openSync, readSync, realpathSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { mkdir, open } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
+const DEFAULT_MAX_LINE_BYTES = 4 * 1024 * 1024;
+const DEFAULT_MAX_RECORD_BYTES = DEFAULT_MAX_LINE_BYTES * 8 + 4096;
+const DEFAULT_MAX_STDERR_BYTES = 64 * 1024;
+const DEFAULT_SHUTDOWN_GRACE_MS = 250;
+const DEFAULT_KILL_GRACE_MS = 250;
+const DEFAULT_MAX_IN_MEMORY_OBSERVATIONS = 1024;
+// A frame observation retains both the original line and parsed payload. Keep
+// the same conservative envelope sizing used for internally owned writers
+// when a caller supplies a writer with a smaller record bound.
+const PROTOCOL_RECORD_ENVELOPE_MULTIPLIER = 8;
+const PROTOCOL_RECORD_ENVELOPE_OVERHEAD = 4096;
+const MAX_TIMER_MS = 2_147_483_647;
+const INTERNAL_RECORDER_TOKEN = Symbol("internal recorder event");
+const CLAIMED_WRITER_PATHS = new Set();
+/**
+ * Appends JSON records one line at a time and optionally fsyncs each append.
+ * A queued writer keeps records ordered even when protocol callbacks overlap.
+ */
+export class JsonlEvidenceWriter {
+    path;
+    maxLineBytes;
+    shouldFsync;
+    exclusive;
+    handle;
+    queue = Promise.resolve();
+    closed = false;
+    poisoned = false;
+    claimed = false;
+    preparedExclusive = false;
+    hasWrites = false;
+    claimLockFd;
+    claimLockPath;
+    claimCanonicalPath;
+    _count = 0;
+    constructor(path, options = {}) {
+        if (path.trim() === "")
+            throw new Error("JSONL evidence path is required.");
+        this.path = resolve(path);
+        this.maxLineBytes = positiveInteger(options.maxLineBytes ?? DEFAULT_MAX_RECORD_BYTES, "JSONL line limit");
+        this.shouldFsync = options.fsync ?? true;
+        this.exclusive = options.exclusive ?? false;
+    }
+    get count() {
+        return this._count;
+    }
+    get maxRecordBytes() {
+        return this.maxLineBytes;
+    }
+    append(record, token) {
+        if (this.poisoned)
+            return Promise.reject(new Error("JSONL evidence writer is unusable after an ambiguous append."));
+        if (this.claimed && token !== INTERNAL_RECORDER_TOKEN) {
+            return Promise.reject(new Error("JSONL evidence writer is claimed by a protocol recorder."));
+        }
+        if (!isRecord(record))
+            return Promise.reject(new Error("JSONL evidence records must be objects."));
+        let line;
+        try {
+            assertJsonValue(record, "JSONL evidence record", new Set());
+            line = `${JSON.stringify(record)}\n`;
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        if (Buffer.byteLength(line) > this.maxLineBytes) {
+            return Promise.reject(new Error(`JSONL evidence record exceeds ${this.maxLineBytes} bytes.`));
+        }
+        this.hasWrites = true;
+        const operation = this.queue.then(async () => {
+            let directLockFd;
+            let directLockPath;
+            try {
+                if (token !== INTERNAL_RECORDER_TOKEN) {
+                    const canonicalPath = canonicalWriterPath(this.path);
+                    directLockPath = `${canonicalPath}.protocol.lock`;
+                    mkdirSync(dirname(canonicalPath), { recursive: true, mode: 0o700 });
+                    try {
+                        directLockFd = openSync(directLockPath, "wx", 0o600);
+                    }
+                    catch (error) {
+                        throw new Error(`JSONL evidence path is reserved by a protocol recorder: ${errorMessage(error)}`);
+                    }
+                }
+                if (this.closed)
+                    throw new Error("JSONL evidence writer is closed.");
+                const handle = await this.openHandle();
+                let wrote = false;
+                try {
+                    const bytes = Buffer.from(line, "utf8");
+                    let offset = 0;
+                    while (offset < bytes.length) {
+                        const { bytesWritten } = await handle.write(bytes.subarray(offset));
+                        if (bytesWritten <= 0)
+                            throw new Error("JSONL evidence write made no progress.");
+                        wrote = true;
+                        offset += bytesWritten;
+                    }
+                    if (this.shouldFsync)
+                        await handle.sync();
+                    this._count += 1;
+                }
+                catch (error) {
+                    if (wrote)
+                        this.poisoned = true;
+                    throw error;
+                }
+            }
+            finally {
+                if (directLockFd !== undefined && directLockPath !== undefined) {
+                    closeSync(directLockFd);
+                    try {
+                        unlinkSync(directLockPath);
+                    }
+                    catch {
+                        // Preserve the append result; a missing lock is already released.
+                    }
+                }
+            }
+        });
+        this.queue = operation.catch(() => undefined);
+        return operation;
+    }
+    flush() {
+        const operation = this.queue.then(async () => {
+            if (this.handle !== undefined && this.shouldFsync)
+                await this.handle.sync();
+        });
+        this.queue = operation.catch(() => undefined);
+        return operation;
+    }
+    close() {
+        const operation = this.queue.then(async () => {
+            if (this.closed) {
+                this.releaseClaimNow();
+                return;
+            }
+            this.closed = true;
+            try {
+                if (this.handle !== undefined) {
+                    await this.handle.close();
+                    this.handle = undefined;
+                }
+            }
+            finally {
+                this.releaseClaimNow();
+            }
+        });
+        this.queue = operation.catch(() => undefined);
+        return operation;
+    }
+    ensureOpen() {
+        const operation = this.queue.then(async () => {
+            if (this.closed)
+                throw new Error("JSONL evidence writer is closed.");
+            await this.openHandle();
+        });
+        this.queue = operation.catch(() => undefined);
+        return operation;
+    }
+    claim(token) {
+        if (this.closed)
+            throw new Error("JSONL evidence writer is closed.");
+        if (this.claimed)
+            throw new Error("JSONL evidence writer is already claimed by a protocol recorder.");
+        const canonicalPath = canonicalWriterPath(this.path);
+        if (CLAIMED_WRITER_PATHS.has(canonicalPath))
+            throw new Error("JSONL evidence path is already claimed by a protocol recorder.");
+        rejectHardLinkedPath(canonicalPath);
+        if (this.hasWrites)
+            throw new Error("JSONL evidence writer cannot be claimed after direct writes.");
+        if (token !== INTERNAL_RECORDER_TOKEN)
+            throw new Error("JSONL evidence writer claim is internal.");
+        mkdirSync(dirname(canonicalPath), { recursive: true, mode: 0o700 });
+        const lockPath = `${canonicalPath}.protocol.lock`;
+        let lockFd;
+        try {
+            lockFd = openSync(lockPath, "wx", 0o600);
+            writeSync(lockFd, `${process.pid}\n`, undefined, "utf8");
+            fsyncSync(lockFd);
+            syncDirectory(dirname(lockPath));
+            this.prepareForClaim();
+            const sequence = recoverWriterSequence(this.path, this.maxLineBytes);
+            this.claimed = true;
+            this.claimLockFd = lockFd;
+            this.claimLockPath = lockPath;
+            this.claimCanonicalPath = canonicalPath;
+            CLAIMED_WRITER_PATHS.add(canonicalPath);
+            return sequence;
+        }
+        catch (error) {
+            if (lockFd !== undefined) {
+                closeSync(lockFd);
+                try {
+                    unlinkSync(lockPath);
+                    syncDirectory(dirname(lockPath));
+                }
+                catch {
+                    // Preserve the original claim/recovery error.
+                }
+            }
+            throw error;
+        }
+    }
+    releaseClaim(token) {
+        if (token !== INTERNAL_RECORDER_TOKEN)
+            throw new Error("JSONL evidence writer release is internal.");
+        this.releaseClaimNow();
+    }
+    releaseClaimNow() {
+        this.claimed = false;
+        if (this.claimLockFd === undefined || this.claimLockPath === undefined)
+            return;
+        const lockFd = this.claimLockFd;
+        const lockPath = this.claimLockPath;
+        const canonicalPath = this.claimCanonicalPath;
+        this.claimLockFd = undefined;
+        this.claimLockPath = undefined;
+        this.claimCanonicalPath = undefined;
+        if (canonicalPath !== undefined)
+            CLAIMED_WRITER_PATHS.delete(canonicalPath);
+        closeSync(lockFd);
+        try {
+            unlinkSync(lockPath);
+            syncDirectory(dirname(lockPath));
+        }
+        catch {
+            // A missing lock is already released; other errors do not change the closed writer state.
+        }
+    }
+    async openHandle() {
+        if (this.handle !== undefined)
+            return this.handle;
+        await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+        const mode = this.preparedExclusive ? "a" : this.exclusive ? "wx" : "a";
+        const handle = await open(this.path, mode, 0o600);
+        try {
+            syncDirectory(dirname(this.path));
+            this.preparedExclusive = false;
+            this.handle = handle;
+            return handle;
+        }
+        catch (error) {
+            await handle.close().catch(() => undefined);
+            throw error;
+        }
+    }
+    prepareForClaim() {
+        if (this.handle !== undefined)
+            return;
+        mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+        const descriptor = openSync(this.path, this.exclusive ? "wx" : "a", 0o600);
+        try {
+            fsyncSync(descriptor);
+        }
+        finally {
+            closeSync(descriptor);
+        }
+        syncDirectory(dirname(this.path));
+        this.preparedExclusive = this.exclusive;
+    }
+}
+export async function openJsonlEvidenceWriter(path, options = {}) {
+    const writer = new JsonlEvidenceWriter(path, options);
+    await writer.ensureOpen();
+    return writer;
+}
+/** Keeps a bounded diagnostic prefix while continuing to drain the stream. */
+export class BoundedDiagnosticCapture {
+    maxBytes;
+    chunks = [];
+    _sizeBytes = 0;
+    _truncated = false;
+    keptBytes = 0;
+    constructor(maxBytes = DEFAULT_MAX_STDERR_BYTES) {
+        this.maxBytes = maxBytes;
+        if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {
+            throw new Error("Diagnostic byte limit must be a nonnegative safe integer.");
+        }
+    }
+    write(chunk) {
+        const bytes = Buffer.from(chunk);
+        this._sizeBytes += bytes.length;
+        const kept = Math.max(0, Math.min(bytes.length, this.maxBytes - this.keptBytes));
+        if (kept > 0) {
+            this.chunks.push(bytes.subarray(0, kept));
+            this.keptBytes += kept;
+        }
+        if (kept < bytes.length)
+            this._truncated = true;
+    }
+    get sizeBytes() {
+        return this._sizeBytes;
+    }
+    get truncated() {
+        return this._truncated;
+    }
+    result() {
+        const bytes = Buffer.concat(this.chunks);
+        return {
+            bytes,
+            text: bytes.toString("utf8"),
+            sizeBytes: this._sizeBytes,
+            truncated: this._truncated,
+            maxBytes: this.maxBytes,
+        };
+    }
+}
+export class ProtocolEvidenceRecorder {
+    writer;
+    source;
+    now;
+    sequence = 0;
+    records = [];
+    maxInMemoryObservations;
+    queue = Promise.resolve();
+    fenced = false;
+    _dropped = 0;
+    constructor(writer, source, now = () => new Date().toISOString(), maxInMemoryObservations = DEFAULT_MAX_IN_MEMORY_OBSERVATIONS) {
+        this.writer = writer;
+        this.source = source;
+        this.now = now;
+        assertNonEmpty(source, "Protocol source");
+        this.maxInMemoryObservations = positiveInteger(maxInMemoryObservations, "In-memory observation limit");
+        this.sequence = writer.claim(INTERNAL_RECORDER_TOKEN);
+    }
+    get observations() {
+        return this.records.map((record) => structuredClone(record));
+    }
+    get droppedObservations() {
+        return this._dropped;
+    }
+    /** Prevents late observer callbacks from appending after process finalization. */
+    fence() {
+        this.fenced = true;
+    }
+    recordFrame(payload, observedAt = this.now(), raw, parseError) {
+        if (payload === undefined && parseError === undefined)
+            return Promise.reject(new Error("Frame payload is required."));
+        if (raw !== undefined)
+            assertNonEmpty(raw, "Raw frame text");
+        if (parseError !== undefined)
+            assertNonEmpty(parseError, "Frame parse error");
+        return this.record({
+            kind: "frame",
+            source: this.source,
+            stream: "stdout",
+            ...(raw === undefined ? {} : { raw }),
+            ...(parseError === undefined ? { payload } : { parseError }),
+            observedAt,
+        });
+    }
+    recordRequest(input) {
+        return this.record({ ...input, kind: "request", observedAt: input.observedAt ?? this.now() });
+    }
+    recordResponse(input) {
+        return this.record({ ...input, kind: "response", observedAt: input.observedAt ?? this.now() });
+    }
+    recordNotification(input) {
+        return this.record({ ...input, kind: "notification", observedAt: input.observedAt ?? this.now() });
+    }
+    recordCompletion(input) {
+        assertNonEmpty(input.source, "Completion source");
+        assertNonEmpty(input.status, "Completion status");
+        if (input.evidence === undefined)
+            return Promise.reject(new Error("Completion evidence is required."));
+        return this.record({
+            kind: "completion",
+            source: input.source,
+            ...(input.method === undefined ? {} : { method: input.method }),
+            ...(input.sourceIdentity === undefined ? {} : { sourceIdentity: input.sourceIdentity }),
+            evidence: input.evidence,
+            status: input.status,
+            observedAt: input.observedAt ?? this.now(),
+        });
+    }
+    recordCapability(input) {
+        assertNonEmpty(input.source, "Capability source");
+        assertNonEmpty(input.name, "Capability name");
+        if (!["available", "unsupported", "missing", "not-checked"].includes(String(input.status))) {
+            return Promise.reject(new Error("Capability status is invalid."));
+        }
+        return this.record({
+            kind: "capability",
+            source: input.source,
+            capability: input.name,
+            status: input.status,
+            ...(input.details === undefined ? {} : { evidence: input.details }),
+            observedAt: input.observedAt ?? this.now(),
+        });
+    }
+    recordError(message, evidence, token) {
+        assertNonEmpty(message, "Protocol error");
+        return this.record({
+            kind: "error",
+            source: this.source,
+            status: message,
+            ...(evidence === undefined ? {} : { evidence }),
+            observedAt: this.now(),
+        }, token === INTERNAL_RECORDER_TOKEN);
+    }
+    recordProcess(status, evidence, token) {
+        assertNonEmpty(status, "Process status");
+        return this.record({
+            kind: "process",
+            source: this.source,
+            status,
+            ...(evidence === undefined ? {} : { evidence }),
+            observedAt: this.now(),
+        }, token === INTERNAL_RECORDER_TOKEN);
+    }
+    flush() {
+        return this.queue.then(() => this.writer.flush());
+    }
+    close() {
+        return this.queue.then(() => this.writer.close());
+    }
+    record(input, allowFenced = false) {
+        if (this.fenced && !allowFenced)
+            return Promise.reject(new Error("Protocol evidence recorder is fenced."));
+        assertNonEmpty(input.source, "Protocol source");
+        assertNonEmpty(input.observedAt, "Observation timestamp");
+        if (input.method !== undefined)
+            assertNonEmpty(input.method, "Protocol method");
+        if (input.sourceIdentity !== undefined)
+            assertNonEmpty(input.sourceIdentity, "Protocol source identity");
+        if (input.id !== undefined && (typeof input.id === "number" && !Number.isFinite(input.id)
+            || typeof input.id !== "string" && typeof input.id !== "number" && input.id !== null)) {
+            return Promise.reject(new Error("Protocol identity must be a finite JSON string, number, or null."));
+        }
+        let payload;
+        let evidence;
+        try {
+            if (input.payload !== undefined)
+                payload = cloneJsonValue(input.payload, "payload");
+            if (input.evidence !== undefined)
+                evidence = cloneJsonValue(input.evidence, "evidence");
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        const operation = this.queue.then(async () => {
+            const observation = {
+                schemaVersion: "ebo.protocol-observation/v1",
+                sequence: this.sequence + 1,
+                observedAt: input.observedAt,
+                kind: input.kind,
+                source: input.source,
+                ...(input.stream === undefined ? {} : { stream: input.stream }),
+                ...(input.method === undefined ? {} : { method: input.method }),
+                ...(input.id === undefined ? {} : { id: input.id }),
+                ...(input.sourceIdentity === undefined ? {} : { sourceIdentity: input.sourceIdentity }),
+                ...(input.raw === undefined ? {} : { raw: input.raw }),
+                ...(input.parseError === undefined ? {} : { parseError: input.parseError }),
+                ...(payload === undefined ? {} : { payload }),
+                ...(evidence === undefined ? {} : { evidence }),
+                ...(input.status === undefined ? {} : { status: input.status }),
+                ...(input.capability === undefined ? {} : { capability: input.capability }),
+            };
+            await this.writer.append(observation, INTERNAL_RECORDER_TOKEN);
+            this.sequence = observation.sequence;
+            if (this.records.length >= this.maxInMemoryObservations) {
+                this.records.shift();
+                this._dropped += 1;
+            }
+            this.records.push(observation);
+            return structuredClone(observation);
+        });
+        this.queue = operation.then(() => undefined, () => undefined);
+        return operation;
+    }
+}
+export class ProtocolProcess {
+    options;
+    child;
+    recorder;
+    stderrCapture;
+    stdoutLineLimit;
+    shutdownGraceMs;
+    killGraceMs;
+    maxInMemoryObservations;
+    writer;
+    now;
+    command;
+    detached;
+    ownsWriter;
+    evidencePath;
+    stderrPath;
+    stderrPersisted = false;
+    startedAt;
+    cwd;
+    args;
+    onFrame;
+    nextLineNumber = 1;
+    frameCount = 0;
+    lineQueue = Promise.resolve();
+    pendingLineParts = [];
+    pendingLineBytes = 0;
+    protocolFailureQueued = false;
+    waitPromise;
+    termination = "natural";
+    protocolError;
+    recorderError;
+    childError;
+    signalQueue = Promise.resolve();
+    abortListener;
+    closeObserved = false;
+    finishStarted = false;
+    resolveResult;
+    constructor(options) {
+        this.options = options;
+        assertNonEmpty(options.command, "Protocol command");
+        assertNonEmpty(options.source, "Protocol source");
+        const requestedLineLimit = positiveInteger(options.maxLineBytes ?? DEFAULT_MAX_LINE_BYTES, "Protocol line limit");
+        this.stderrCapture = new BoundedDiagnosticCapture(options.maxStderrBytes ?? DEFAULT_MAX_STDERR_BYTES);
+        this.shutdownGraceMs = nonnegativeInteger(options.shutdownGraceMs ?? DEFAULT_SHUTDOWN_GRACE_MS, "Shutdown grace period");
+        this.killGraceMs = nonnegativeInteger(options.killGraceMs ?? DEFAULT_KILL_GRACE_MS, "Kill grace period");
+        if (this.shutdownGraceMs > MAX_TIMER_MS)
+            throw new Error("Shutdown grace period must not exceed the Node timer maximum.");
+        if (this.killGraceMs > MAX_TIMER_MS)
+            throw new Error("Kill grace period must not exceed the Node timer maximum.");
+        this.maxInMemoryObservations = positiveInteger(options.maxInMemoryObservations ?? DEFAULT_MAX_IN_MEMORY_OBSERVATIONS, "In-memory observation limit");
+        this.now = options.now ?? (() => new Date().toISOString());
+        this.command = options.command;
+        this.detached = options.spawnOptions?.detached ?? process.platform !== "win32";
+        this.startedAt = this.now();
+        assertTimestamp(this.startedAt, "Process start timestamp");
+        this.cwd = resolve(options.cwd ?? process.cwd());
+        this.args = [...(options.args ?? [])];
+        this.onFrame = options.onFrame;
+        let writer;
+        if (options.writer !== undefined) {
+            writer = options.writer;
+        }
+        else {
+            const evidencePath = options.evidencePath ?? resolve(process.cwd(), `.ebo-protocol-${randomUUID()}.jsonl`);
+            mkdirSync(dirname(evidencePath), { recursive: true, mode: 0o700 });
+            const descriptor = openSync(evidencePath, "wx", 0o600);
+            closeSync(descriptor);
+            syncDirectory(dirname(resolve(evidencePath)));
+            writer = new JsonlEvidenceWriter(evidencePath, {
+                maxLineBytes: Math.min(Number.MAX_SAFE_INTEGER, requestedLineLimit * 8 + 4096),
+            });
+        }
+        const configuredEvidencePath = options.evidencePath === undefined ? undefined : resolve(options.evidencePath);
+        if (options.writer !== undefined && configuredEvidencePath !== undefined && configuredEvidencePath !== writer.path) {
+            throw new Error("Protocol writer path conflicts with evidencePath.");
+        }
+        this.stdoutLineLimit = protocolLineLimitForWriter(requestedLineLimit, writer.maxRecordBytes, options.writer !== undefined);
+        this.ownsWriter = options.writer === undefined;
+        this.evidencePath = writer.path;
+        this.stderrPath = options.stderrPath === undefined ? undefined : resolve(options.stderrPath);
+        this.writer = writer;
+        this.recorder = new ProtocolEvidenceRecorder(writer, options.source, this.now, this.maxInMemoryObservations);
+        const callerSpawnOptions = { ...options.spawnOptions };
+        delete callerSpawnOptions.signal;
+        delete callerSpawnOptions.timeout;
+        delete callerSpawnOptions.killSignal;
+        const spawnOptions = {
+            ...callerSpawnOptions,
+            cwd: this.cwd,
+            env: options.env,
+            stdio: ["pipe", "pipe", "pipe"],
+            detached: this.detached,
+        };
+        try {
+            this.child = spawn(options.command, this.args, spawnOptions);
+        }
+        catch (error) {
+            this.writer.releaseClaim(INTERNAL_RECORDER_TOKEN);
+            throw error;
+        }
+        this.child.on("error", (error) => {
+            this.childError ??= errorMessage(error);
+            void this.recorder.recordError(this.childError, undefined, INTERNAL_RECORDER_TOKEN).catch(() => undefined);
+        });
+        this.child.stdin?.on("error", (error) => {
+            this.childError ??= `Protocol stdin failed: ${errorMessage(error)}`;
+            void this.recorder.recordError(this.childError, undefined, INTERNAL_RECORDER_TOKEN).catch(() => undefined);
+        });
+        this.attachStreams();
+        this.waitPromise = new Promise((resolveResult) => {
+            this.resolveResult = resolveResult;
+            this.child.once("close", (exitCode, signal) => {
+                this.beginFinish(exitCode, signal);
+            });
+        });
+        const abort = () => {
+            void this.interrupt();
+        };
+        this.abortListener = abort;
+        if (this.options.signal?.aborted)
+            abort();
+        else
+            this.options.signal?.addEventListener("abort", abort, { once: true });
+        if (this.childError !== undefined)
+            void this.recorder.recordError(this.childError, undefined, INTERNAL_RECORDER_TOKEN);
+    }
+    get pid() {
+        return this.child.pid ?? undefined;
+    }
+    get stdin() {
+        if (this.child.stdin === null)
+            throw new Error("Protocol process stdin is unavailable.");
+        return this.child.stdin;
+    }
+    get evidence() {
+        return this.recorder;
+    }
+    wait() {
+        return this.waitPromise;
+    }
+    async shutdown() {
+        if (this.closeObserved)
+            return this.wait();
+        this.setTermination("shutdown");
+        await this.sendSignal("SIGTERM", this.shutdownGraceMs);
+        return this.wait();
+    }
+    async interrupt(graceMs = this.shutdownGraceMs, killGraceMs = this.killGraceMs) {
+        if (this.closeObserved)
+            return this.wait();
+        const boundedGraceMs = nonnegativeInteger(graceMs, "Interrupt grace period");
+        const boundedKillGraceMs = nonnegativeInteger(killGraceMs, "Interrupt kill grace period");
+        if (boundedGraceMs > MAX_TIMER_MS || boundedKillGraceMs > MAX_TIMER_MS) {
+            throw new Error("Interrupt grace periods must not exceed the Node timer maximum.");
+        }
+        this.setTermination("interrupted");
+        await this.sendSignal("SIGINT", boundedGraceMs, boundedKillGraceMs);
+        return this.wait();
+    }
+    attachStreams() {
+        if (this.child.stderr !== null) {
+            this.child.stderr.on("data", (chunk) => {
+                this.stderrCapture.write(chunk);
+                if (this.options.onStderr !== undefined) {
+                    this.child.stderr?.pause();
+                    this.lineQueue = this.lineQueue
+                        .then(() => this.options.onStderr(chunk, false, this.recorder))
+                        .then(() => undefined)
+                        .catch((error) => this.failRecorder(`Protocol stderr recording failed: ${errorMessage(error)}`));
+                    void this.lineQueue.finally(() => this.child.stderr?.resume()).catch(() => undefined);
+                }
+            });
+            this.child.stderr.on("end", () => {
+                if (this.options.onStderr !== undefined) {
+                    this.lineQueue = this.lineQueue
+                        .then(() => this.options.onStderr(Buffer.alloc(0), true, this.recorder))
+                        .then(() => undefined)
+                        .catch((error) => this.failRecorder(`Protocol stderr recording failed: ${errorMessage(error)}`));
+                }
+            });
+        }
+        if (this.child.stdout === null)
+            return;
+        this.child.stdout.on("data", (chunk) => {
+            this.child.stdout?.pause();
+            try {
+                this.consumeStdout(chunk);
+            }
+            catch (error) {
+                void this.failRecorder(`Protocol output processing failed: ${errorMessage(error)}`);
+            }
+            void this.lineQueue.finally(() => this.child.stdout?.resume()).catch(() => undefined);
+        });
+        this.child.stdout.on("end", () => this.flushPendingLine());
+    }
+    consumeStdout(chunk) {
+        if (this.protocolError !== undefined || this.recorderError !== undefined)
+            return;
+        let offset = 0;
+        while (offset < chunk.length) {
+            const newline = chunk.indexOf(0x0a, offset);
+            if (newline === -1) {
+                this.appendPendingLine(chunk.subarray(offset));
+                return;
+            }
+            if (!this.appendPendingLine(chunk.subarray(offset, newline)))
+                return;
+            this.queuePendingLine(this.nextLineNumber);
+            this.nextLineNumber += 1;
+            offset = newline + 1;
+        }
+    }
+    appendPendingLine(part) {
+        if (part.length === 0)
+            return true;
+        this.pendingLineBytes += part.length;
+        if (this.pendingLineBytes > this.stdoutLineLimit) {
+            this.pendingLineParts = [];
+            this.pendingLineBytes = 0;
+            if (!this.protocolFailureQueued) {
+                this.protocolFailureQueued = true;
+                const line = this.nextLineNumber;
+                this.lineQueue = this.lineQueue
+                    .then(() => this.failProtocol(`Protocol line ${line} exceeds the configured byte limit.`, undefined, line))
+                    .catch((error) => this.failRecorder(`Protocol evidence recording failed: ${errorMessage(error)}`));
+            }
+            return false;
+        }
+        this.pendingLineParts.push(part);
+        return true;
+    }
+    queuePendingLine(lineNumber) {
+        const bytes = Buffer.concat(this.pendingLineParts, this.pendingLineBytes);
+        this.pendingLineParts = [];
+        this.pendingLineBytes = 0;
+        this.lineQueue = this.lineQueue
+            .then(() => this.processLine(bytes, lineNumber))
+            .catch((error) => this.failRecorder(`Protocol evidence recording failed: ${errorMessage(error)}`));
+    }
+    flushPendingLine() {
+        if (this.pendingLineBytes > 0 && this.protocolError === undefined && this.recorderError === undefined) {
+            const bytes = Buffer.concat(this.pendingLineParts, this.pendingLineBytes);
+            this.pendingLineParts = [];
+            this.pendingLineBytes = 0;
+            const line = this.nextLineNumber;
+            this.protocolFailureQueued = true;
+            this.lineQueue = this.lineQueue
+                .then(() => this.failProtocol("Unterminated JSONL protocol output.", bytes.toString("base64"), line))
+                .catch((error) => this.failRecorder(`Protocol evidence recording failed: ${errorMessage(error)}`));
+            this.nextLineNumber += 1;
+        }
+    }
+    async processLine(bytes, lineNumber) {
+        if (this.recorderError !== undefined || (this.protocolError !== undefined && lineNumber >= this.protocolError.line))
+            return;
+        let line;
+        try {
+            line = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        }
+        catch (error) {
+            await this.failProtocol(`Malformed UTF-8 protocol output: ${errorMessage(error)}`, bytes.toString("base64"), lineNumber);
+            return;
+        }
+        let payload;
+        try {
+            payload = JSON.parse(line);
+        }
+        catch (error) {
+            await this.failProtocol(`Malformed JSONL protocol output: ${errorMessage(error)}`, line, lineNumber);
+            return;
+        }
+        this.frameCount += 1;
+        const nonFiniteNumberPath = findNonFiniteJsonNumber(payload);
+        const parseError = nonFiniteNumberPath === undefined
+            ? undefined
+            : `Parsed JSON contains a non-finite number at ${nonFiniteNumberPath}; raw frame retained without a JSON-safe payload.`;
+        await this.recorder.recordFrame(nonFiniteNumberPath === undefined ? payload : undefined, this.now(), line, parseError);
+        if (this.onFrame !== undefined) {
+            const observer = Promise.resolve(this.onFrame(payload, this.recorder));
+            const outcome = await settleObserver(observer, this.shutdownGraceMs);
+            if (outcome.status === "failed")
+                throw outcome.error;
+            if (outcome.status === "timed-out") {
+                this.recorder.fence();
+                throw new Error("Protocol frame observer exceeded its grace period.");
+            }
+        }
+    }
+    async failProtocol(message, raw, line = this.nextLineNumber) {
+        if (this.protocolError !== undefined)
+            return;
+        this.protocolError = { line, message, ...(raw === undefined ? {} : { raw }) };
+        this.setTermination("malformed");
+        try {
+            await this.recorder.recordError(message, raw === undefined ? undefined : { raw }, INTERNAL_RECORDER_TOKEN);
+        }
+        catch (error) {
+            this.childError ??= `Protocol error evidence could not be persisted: ${errorMessage(error)}`;
+        }
+        void this.sendSignal("SIGTERM", this.shutdownGraceMs);
+    }
+    async failRecorder(message) {
+        if (this.recorderError !== undefined || this.protocolError !== undefined)
+            return;
+        this.recorderError = message;
+        this.setTermination("recorder-error");
+        try {
+            await this.recorder.recordError(message, undefined, INTERNAL_RECORDER_TOKEN);
+        }
+        catch (error) {
+            this.childError ??= `Protocol error evidence could not be persisted: ${errorMessage(error)}`;
+        }
+        void this.sendSignal("SIGTERM", this.shutdownGraceMs);
+    }
+    setTermination(termination) {
+        if (this.termination === "natural")
+            this.termination = termination;
+    }
+    sendSignal(signal, graceMs, killGraceMs = this.killGraceMs) {
+        const operation = this.signalQueue.then(() => this.sendSignalNow(signal, graceMs, killGraceMs));
+        this.signalQueue = operation.catch(() => undefined);
+        return operation;
+    }
+    async sendSignalNow(signal, graceMs, killGraceMs) {
+        if (this.closeObserved)
+            return;
+        const pid = this.child.pid;
+        if (pid === undefined) {
+            this.forceFinish();
+            return;
+        }
+        try {
+            if (process.platform !== "win32" && this.detached) {
+                process.kill(-pid, signal);
+            }
+            else {
+                this.child.kill(signal);
+            }
+        }
+        catch (error) {
+            if (error.code !== "ESRCH")
+                this.childError ??= errorMessage(error);
+            if (!this.closeObserved)
+                this.forceFinish();
+            return;
+        }
+        if (graceMs > 0)
+            await this.waitForClose(graceMs);
+        if (!this.closeObserved) {
+            try {
+                if (process.platform !== "win32" && this.detached) {
+                    process.kill(-pid, "SIGKILL");
+                }
+                else {
+                    this.child.kill("SIGKILL");
+                }
+            }
+            catch (error) {
+                if (error.code !== "ESRCH")
+                    this.childError ??= errorMessage(error);
+            }
+            if (killGraceMs > 0)
+                await this.waitForClose(killGraceMs);
+        }
+        if (!this.closeObserved && (this.detached || this.child.exitCode !== null || this.child.signalCode !== null)) {
+            this.forceFinish();
+        }
+    }
+    async waitForClose(milliseconds) {
+        if (this.closeObserved)
+            return;
+        await new Promise((resolvePromise) => {
+            const timer = setTimeout(resolvePromise, milliseconds);
+            this.child.once("close", () => {
+                clearTimeout(timer);
+                resolvePromise();
+            });
+        });
+    }
+    beginFinish(exitCode, signal) {
+        if (this.finishStarted || this.resolveResult === undefined)
+            return;
+        this.finishStarted = true;
+        this.closeObserved = true;
+        void this.finish(exitCode, signal, this.resolveResult);
+    }
+    forceFinish() {
+        if (this.closeObserved)
+            return;
+        this.child.stdout?.destroy();
+        this.child.stderr?.destroy();
+        this.beginFinish(this.child.exitCode, this.child.signalCode);
+    }
+    async finish(exitCode, signal, resolveResult) {
+        try {
+            await this.lineQueue;
+        }
+        catch (error) {
+            this.childError ??= `Protocol output processing failed: ${errorMessage(error)}`;
+        }
+        this.recorder.fence();
+        try {
+            await this.recorder.flush();
+            await this.recorder.recordProcess(signal === null && exitCode === 0 ? "exited" : "terminated", { exitCode, signal, pid: this.child.pid ?? null }, INTERNAL_RECORDER_TOKEN);
+            await this.recorder.flush();
+        }
+        catch (error) {
+            this.childError ??= `Protocol evidence could not be persisted: ${errorMessage(error)}`;
+        }
+        if (this.options.signal !== undefined && this.abortListener !== undefined) {
+            this.options.signal.removeEventListener("abort", this.abortListener);
+        }
+        const stderr = this.stderrCapture.result();
+        if (this.stderrPath !== undefined) {
+            let diagnosticFile;
+            try {
+                await mkdir(dirname(this.stderrPath), { recursive: true, mode: 0o700 });
+                diagnosticFile = await open(this.stderrPath, "wx", 0o600);
+                await writeFileHandleFully(diagnosticFile, stderr.bytes, "stderr evidence");
+                await diagnosticFile.sync();
+                await diagnosticFile.close();
+                diagnosticFile = undefined;
+                syncDirectory(dirname(this.stderrPath));
+                this.stderrPersisted = true;
+            }
+            catch (error) {
+                await diagnosticFile?.close().catch(() => undefined);
+                this.childError ??= `stderr evidence could not be persisted: ${errorMessage(error)}`;
+            }
+        }
+        if (this.ownsWriter) {
+            // The process record above is durable before the writer is closed.
+            try {
+                await this.recorder.close();
+            }
+            catch (error) {
+                this.childError ??= `Protocol evidence could not be closed: ${errorMessage(error)}`;
+            }
+        }
+        let endedAt;
+        try {
+            endedAt = this.now();
+            assertTimestamp(endedAt, "Process completion timestamp");
+        }
+        catch (error) {
+            this.childError ??= `Process completion timestamp could not be recorded: ${errorMessage(error)}`;
+            endedAt = this.startedAt;
+        }
+        const termination = this.termination;
+        const status = this.protocolError !== undefined
+            ? "malformed"
+            : this.recorderError !== undefined || this.childError !== undefined
+                ? "failed"
+                : this.termination === "interrupted"
+                    ? "interrupted"
+                    : this.termination === "shutdown"
+                        ? "shutdown"
+                        : exitCode === 0 && signal === null
+                            ? "completed"
+                            : "failed";
+        const result = {
+            status,
+            partial: status === "interrupted" || status === "malformed" || status === "failed",
+            protocolOnly: true,
+            launch: {
+                command: this.command,
+                args: this.args,
+                cwd: this.cwd,
+                pid: this.child.pid ?? null,
+                startedAt: this.startedAt,
+                endedAt,
+                exitCode,
+                signal,
+            },
+            termination,
+            stdoutFrames: this.frameCount,
+            stderr,
+            ...(this.protocolError === undefined ? {} : { protocolError: this.protocolError }),
+            ...(this.childError === undefined && this.recorderError === undefined ? {} : { error: this.childError ?? this.recorderError }),
+            ...(this.recorderError === undefined ? {} : { recorderError: this.recorderError }),
+            ...(this.evidencePath === undefined || this.writer.count === 0 ? {} : { evidencePath: this.evidencePath }),
+            ...(this.stderrPersisted && this.stderrPath !== undefined ? { stderrPath: this.stderrPath } : {}),
+            droppedObservations: this.recorder.droppedObservations,
+            observations: [...this.recorder.observations],
+        };
+        resolveResult(result);
+    }
+}
+export function spawnProtocolProcess(options) {
+    return new ProtocolProcess(options);
+}
+export async function runProtocolProcess(options) {
+    return spawnProtocolProcess(options).wait();
+}
+function syncDirectory(path) {
+    const descriptor = openSync(path, constants.O_RDONLY | constants.O_DIRECTORY);
+    try {
+        fsyncSync(descriptor);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+async function writeFileHandleFully(handle, bytes, label) {
+    let offset = 0;
+    while (offset < bytes.length) {
+        const { bytesWritten } = await handle.write(bytes.subarray(offset));
+        if (bytesWritten <= 0)
+            throw new Error(`${label} write made no progress.`);
+        offset += bytesWritten;
+    }
+}
+function protocolLineLimitForWriter(requestedLineLimit, writerMaxRecordBytes, callerSuppliedWriter) {
+    if (!callerSuppliedWriter)
+        return requestedLineLimit;
+    if (writerMaxRecordBytes <= PROTOCOL_RECORD_ENVELOPE_OVERHEAD) {
+        throw new Error("JSONL evidence writer is too small for a protocol observation envelope.");
+    }
+    const available = writerMaxRecordBytes - PROTOCOL_RECORD_ENVELOPE_OVERHEAD;
+    const envelopeSafeLimit = Math.max(1, Math.floor(available / PROTOCOL_RECORD_ENVELOPE_MULTIPLIER));
+    return Math.min(requestedLineLimit, envelopeSafeLimit);
+}
+function canonicalWriterPath(path) {
+    try {
+        return realpathSync.native(path);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        let parent;
+        try {
+            parent = realpathSync.native(dirname(path));
+        }
+        catch (parentError) {
+            if (parentError.code !== "ENOENT")
+                throw parentError;
+            parent = resolve(dirname(path));
+        }
+        return resolve(parent, basename(path));
+    }
+}
+function isHardLinkedPath(path) {
+    try {
+        return statSync(path).nlink > 1;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function rejectHardLinkedPath(path) {
+    if (isHardLinkedPath(path))
+        throw new Error("JSONL evidence path has multiple hard links and cannot be claimed safely.");
+}
+function recoverWriterSequence(path, maxLineBytes) {
+    let descriptor;
+    try {
+        descriptor = openSync(path, "r");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return 0;
+        throw error;
+    }
+    let sequence = 0;
+    let lineNumber = 1;
+    let lineParts = [];
+    let lineBytes = 0;
+    const buffer = Buffer.allocUnsafe(64 * 1024);
+    try {
+        while (true) {
+            const bytesRead = readSync(descriptor, buffer, 0, buffer.length, null);
+            if (bytesRead === 0)
+                break;
+            const chunk = buffer.subarray(0, bytesRead);
+            let offset = 0;
+            while (offset < chunk.length) {
+                const newline = chunk.indexOf(0x0a, offset);
+                const end = newline === -1 ? chunk.length : newline;
+                const part = chunk.subarray(offset, end);
+                if (part.length > 0) {
+                    lineBytes += part.length;
+                    if (lineBytes > maxLineBytes) {
+                        throw new Error(`Existing JSONL evidence line ${lineNumber} exceeds ${maxLineBytes} bytes.`);
+                    }
+                    lineParts.push(Buffer.from(part));
+                }
+                if (newline === -1)
+                    break;
+                const line = decodeRecoveredLine(lineParts, lineBytes, lineNumber);
+                const value = parseRecoveredObservation(line, lineNumber);
+                if (value.sequence !== sequence + 1) {
+                    throw new Error(`Existing JSONL evidence line ${lineNumber} is not a contiguous protocol observation.`);
+                }
+                sequence = value.sequence;
+                lineNumber += 1;
+                lineParts = [];
+                lineBytes = 0;
+                offset = newline + 1;
+            }
+        }
+        if (lineBytes > 0) {
+            throw new Error("Existing JSONL evidence stream has an unterminated final record.");
+        }
+        return sequence;
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+function decodeRecoveredLine(parts, bytes, line) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(parts, bytes));
+    }
+    catch (error) {
+        throw new Error(`Existing JSONL evidence line ${line} is malformed: ${errorMessage(error)}`);
+    }
+}
+function parseRecoveredObservation(line, lineNumber) {
+    if (line.trim() === "")
+        throw new Error(`Existing JSONL evidence line ${lineNumber} is blank.`);
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch (error) {
+        throw new Error(`Existing JSONL evidence line ${lineNumber} is malformed: ${errorMessage(error)}`);
+    }
+    assertProtocolObservation(value, lineNumber);
+    return value;
+}
+/** Validate a retained protocol envelope against its physical JSONL line. */
+export function assertProtocolObservation(value, lineNumber) {
+    const candidate = isRecord(value) ? value.sequence : undefined;
+    if (!isRecord(value) || value.schemaVersion !== "ebo.protocol-observation/v1"
+        || !Number.isSafeInteger(lineNumber) || lineNumber < 1
+        || typeof candidate !== "number" || !Number.isSafeInteger(candidate) || candidate !== lineNumber) {
+        throw new Error(`Existing JSONL evidence line ${lineNumber} is not a contiguous protocol observation.`);
+    }
+    assertRecoveredObservation(value, lineNumber);
+}
+function assertRecoveredObservation(value, line) {
+    if (typeof value.observedAt !== "string" || value.observedAt.trim() === "") {
+        throw new Error(`Existing JSONL evidence line ${line} has no valid observation timestamp.`);
+    }
+    const kind = value.kind;
+    if (!["frame", "request", "response", "notification", "completion", "capability", "error", "process"].includes(String(kind))) {
+        throw new Error(`Existing JSONL evidence line ${line} has an invalid observation kind.`);
+    }
+    if (typeof value.source !== "string" || value.source.trim() === "") {
+        throw new Error(`Existing JSONL evidence line ${line} has no valid observation source.`);
+    }
+    if (value.stream !== undefined && value.stream !== "stdout" && value.stream !== "stderr") {
+        throw new Error(`Existing JSONL evidence line ${line} has an invalid observation stream.`);
+    }
+    for (const field of ["method", "sourceIdentity", "raw", "parseError", "status", "capability"]) {
+        if (value[field] !== undefined && (typeof value[field] !== "string" || value[field].trim() === "")) {
+            throw new Error(`Existing JSONL evidence line ${line} has an invalid ${field}.`);
+        }
+    }
+    if (value.id !== undefined && (typeof value.id === "number" && !Number.isFinite(value.id)
+        || typeof value.id !== "string" && typeof value.id !== "number" && value.id !== null)) {
+        throw new Error(`Existing JSONL evidence line ${line} has an invalid protocol identity.`);
+    }
+    if (kind === "frame" && !Object.hasOwn(value, "payload")) {
+        if (typeof value.parseError !== "string" || value.parseError.trim() === "") {
+            throw new Error(`Existing JSONL evidence line ${line} is missing frame payload.`);
+        }
+    }
+    else if (kind === "frame" && value.parseError !== undefined) {
+        throw new Error(`Existing JSONL evidence line ${line} has contradictory frame payload evidence.`);
+    }
+    else if (kind !== "frame" && value.parseError !== undefined) {
+        throw new Error(`Existing JSONL evidence line ${line} has an unexpected frame parse error.`);
+    }
+    if ((kind === "request" || kind === "response" || kind === "notification")
+        && (typeof value.method !== "string" || value.method.trim() === "")) {
+        throw new Error(`Existing JSONL evidence line ${line} is missing protocol method.`);
+    }
+    if (kind === "completion" && (!Object.hasOwn(value, "evidence") || typeof value.status !== "string" || value.status.trim() === "")) {
+        throw new Error(`Existing JSONL evidence line ${line} is missing completion evidence.`);
+    }
+    if (kind === "capability" && (typeof value.capability !== "string" || value.capability.trim() === ""
+        || !["available", "unsupported", "missing", "not-checked"].includes(String(value.status)))) {
+        throw new Error(`Existing JSONL evidence line ${line} has invalid capability evidence.`);
+    }
+    if ((kind === "error" || kind === "process") && (typeof value.status !== "string" || value.status.trim() === "")) {
+        throw new Error(`Existing JSONL evidence line ${line} is missing status evidence.`);
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function assertNonEmpty(value, label) {
+    if (value.trim() === "")
+        throw new Error(`${label} is required.`);
+}
+function assertTimestamp(value, label) {
+    if (typeof value !== "string" || value.trim() === "")
+        throw new Error(`${label} is invalid.`);
+}
+function positiveInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value < 1)
+        throw new Error(`${label} must be a positive safe integer.`);
+    return value;
+}
+function nonnegativeInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new Error(`${label} must be a nonnegative safe integer.`);
+    return value;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function cloneJsonValue(value, label) {
+    assertJsonValue(value, label, new Set());
+    return structuredClone(value);
+}
+function findNonFiniteJsonNumber(value, path = "$", seen = new Set()) {
+    if (typeof value === "number")
+        return Number.isFinite(value) ? undefined : path;
+    if (value === null || typeof value !== "object")
+        return undefined;
+    if (seen.has(value))
+        return undefined;
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (const [index, item] of value.entries()) {
+            const result = findNonFiniteJsonNumber(item, `${path}[${index}]`, seen);
+            if (result !== undefined)
+                return result;
+        }
+    }
+    else {
+        for (const [key, item] of Object.entries(value)) {
+            const result = findNonFiniteJsonNumber(item, `${path}.${key}`, seen);
+            if (result !== undefined)
+                return result;
+        }
+    }
+    seen.delete(value);
+    return undefined;
+}
+function assertJsonValue(value, path, seen) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error(`${path} must be a finite JSON number.`);
+        return;
+    }
+    if (typeof value !== "object")
+        throw new Error(`${path} contains a non-JSON value.`);
+    if (seen.has(value))
+        throw new Error(`${path} contains a cycle.`);
+    seen.add(value);
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => assertJsonValue(item, `${path}[${index}]`, seen));
+    }
+    else {
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null)
+            throw new Error(`${path} must be a JSON object or array.`);
+        const object = value;
+        for (const key of Object.keys(object))
+            assertJsonValue(object[key], `${path}.${key}`, seen);
+    }
+    seen.delete(value);
+}
+async function settleObserver(promise, milliseconds) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise.then((value) => ({ status: "completed", value }), (error) => ({ status: "failed", error })),
+            new Promise((resolvePromise) => {
+                timer = setTimeout(() => resolvePromise({ status: "timed-out" }), milliseconds);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}