docs(process): preserve capture invariants
This commit is contained in:
@@ -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,
|
||||
|
||||
@@ -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 ?? [];
|
||||
|
||||
@@ -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()) {
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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();
|
||||
|
||||
Reference in New Issue
Block a user