docs(process): preserve capture invariants

This commit is contained in:
morluto
2026-07-13 17:15:22 +08:00
parent ba15d16c58
commit 841990bde1
33 changed files with 214 additions and 128 deletions
+7 -1
View File
@@ -41,7 +41,13 @@ else process.exit(route.termination.code);
const shellQuote = (value: string): string =>
`'${value.replaceAll("'", `'\\''`)}'`;
/** Start bounded executable replay wrappers and their private invocation ledger. */
/**
* Start bounded executable replay wrappers and their private invocation ledger.
*
* Exact argument matching is deliberate: a fallback to the host executable
* would make an unmatched dependency call look authoritative. Unmatched and
* exhausted routes therefore fail visibly and remain part of the capture.
*/
export const startCommandShimReplay = async (
scenario: ProcessScenario,
temporaryRoot: string,
+3
View File
@@ -96,6 +96,9 @@ export class ProcessCheckpoints {
capture(name: string): void {
if (this.#captured.has(name)) return;
this.#captured.add(name);
// Serialize scans even when time, terminal, and lifecycle triggers fire
// together. Each effect set is intentionally relative to the immediately
// preceding checkpoint, which preserves transient create/delete behavior.
this.#pending = this.#pending.then(async () => {
const snapshot = await snapshotRoots(this.scenario, this.signal);
const previous = this.#captures.at(-1)?.files ?? [];
+8 -1
View File
@@ -1,7 +1,7 @@
import { randomUUID } from "node:crypto";
import { mkdtemp, realpath, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { join } from "node:path";
import { spawn, type IPty } from "node-pty";
import type {
FilesystemCheckpoint,
@@ -139,6 +139,10 @@ const makeEnvironment = (
environment.REA_REPLAY_HTTP_URL = replay.httpUrl;
environment.REA_REPLAY_WEBSOCKET_URL = replay.websocketUrl;
environment.REA_SHIM_LEDGER_URL = shimReplay.url;
// PATH is evidence-producing input. Inheriting the host PATH here would let
// the authority and reconstruction probe different tools without recording
// that difference. Scenarios must opt in through environment or
// inherit_environment; deterministic shims always take precedence.
environment.PATH = [shimReplay.binPath, environment.PATH ?? ""]
.filter((part) => part.length > 0)
.join(":");
@@ -315,6 +319,9 @@ const awaitTerminalExit = async ({
reason: "exited" | "timeout" | "idle_timeout" | "cancelled";
}> =>
new Promise((resolveExit) => {
// The kill caused by a deadline is observed later as an ordinary PTY exit.
// Keep the initiating lifecycle reason so comparisons distinguish a target
// exit from harness-owned timeout, idle-timeout, and cancellation cleanup.
let reason: "exited" | "timeout" | "idle_timeout" | "cancelled" = "exited";
terminal.onExit((exit) => {
for (const [eventIndex, event] of scenario.events.entries()) {
+10 -1
View File
@@ -4,6 +4,7 @@ import { promisify } from "node:util";
const execFileAsync = promisify(execFile);
/** Identity proof required before REA may signal a captured process group. */
export interface OwnedProcessGroup {
readonly runId: string;
readonly leaderPid: number;
@@ -21,12 +22,14 @@ interface ProcessGroupMember {
readonly command: string;
}
/** Narrow operating-system seam used to inspect and signal process groups. */
export interface ProcessOwnershipHost {
listMembers(processGroupId: number): Promise<readonly ProcessGroupMember[]>;
environment(pid: number): Promise<Readonly<Record<string, string>>>;
signalGroup(processGroupId: number, signal: NodeJS.Signals): void;
}
/** Cleanup succeeds only when the group is absent or every member is owned. */
export type ProcessCleanupResult =
| { readonly cleaned: true; readonly signaled: boolean }
| { readonly cleaned: false; readonly reason: string };
@@ -78,7 +81,13 @@ const systemHost: ProcessOwnershipHost = {
},
};
/** Verify run-token ownership before signaling a POSIX process group. */
/**
* Verify run-token ownership before signaling a POSIX process group.
*
* Process IDs and group IDs can be reused. REA therefore re-reads every live
* member's environment immediately before signaling and fails closed if any
* member cannot be inspected or lacks the per-capture run token.
*/
export const cleanupOwnedProcessGroup = async (
ownership: OwnedProcessGroup,
host: ProcessOwnershipHost = systemHost,
+7
View File
@@ -20,6 +20,13 @@ interface TerminalRendererOptions {
}
/** Owns one headless terminal and serializes writes into deterministic frames. */
/**
* Reconstructs bounded terminal states while raw PTY chunks remain authoritative.
*
* Rendered frames answer what an operator saw after control-sequence handling;
* raw frames preserve byte/chunk differences that can render identically.
* Comparisons retain both because neither representation subsumes the other.
*/
export class TerminalRenderer {
readonly #terminal: InstanceType<typeof HeadlessPackage.Terminal>;
readonly #serializeAddon = new SerializePackage.SerializeAddon();