rea-agents 2.0.0 → 2.2.0

package/dist/application/MacHopper.js

@@ -10,6 +10,16 @@ const RELEASES_URL = "https://www.hopperapp.com/include/files-api.php?request=re
 const DOWNLOAD_PREFIX = "https://www.hopperapp.com:443/downloader/public/";
 const MAX_PACKAGE_BYTES = 100_000_000;
 const BUNDLE_IDENTIFIER = "com.cryptic-apps.hopper-web-4";
+/** Stable network and command effects disclosed before macOS Hopper setup. */
+export const macHopperInstallDisclosure = {
+    networkOrigins: [RELEASES_URL, DOWNLOAD_PREFIX],
+    commands: [
+        "hdiutil attach -readonly -nobrowse -mountpoint <private-mount> <verified-hopper.dmg>",
+        "codesign --verify --deep --strict <mounted-hopper.app>",
+        "ditto <mounted-hopper.app> <user-Applications-stage>",
+        "open <installed-hopper.app>",
+    ],
+};
 /** Download, verify, and install Hopper into the current user's Applications directory. */
 export const installMacHopper = async (options = {}, host = systemMacHopperInstallHost()) => {
     let temporary;
@@ -66,17 +76,7 @@ export const installMacHopper = async (options = {}, host = systemMacHopperInsta
     }
 };
 const systemMacHopperInstallHost = () => ({
-    async download(url) {
-        const response = await fetch(url, {
-            headers: { accept: "application/json", "user-agent": "rea-installer" },
-            signal: AbortSignal.timeout(120_000),
-        });
-        const length = Number(response.headers.get("content-length") ?? "0");
-        if (length > MAX_PACKAGE_BYTES)
-            return { ok: false, bytes: new Uint8Array() };
-        const bytes = new Uint8Array(await response.arrayBuffer());
-        return { ok: response.ok && bytes.byteLength <= MAX_PACKAGE_BYTES, bytes };
-    },
+    download: downloadPackage,
     createTemporaryDirectory: () => mkdtemp(join(tmpdir(), "rea-hopper-mac-")),
     createMountDirectory: (path) => mkdir(path),
     writePackage: (path, bytes) => writeFile(path, bytes, { mode: 0o600 }),
@@ -170,6 +170,17 @@ const systemMacHopperInstallHost = () => ({
     cleanup: (path) => rm(path, { recursive: true, force: true }),
     destination: () => join(homedir(), "Applications/Hopper Disassembler.app"),
 });
+const downloadPackage = async (url) => {
+    const response = await fetch(url, {
+        headers: { accept: "application/json", "user-agent": "rea-installer" },
+        signal: AbortSignal.timeout(120_000),
+    });
+    const length = Number(response.headers.get("content-length") ?? "0");
+    if (length > MAX_PACKAGE_BYTES)
+        return { ok: false, bytes: new Uint8Array() };
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    return { ok: response.ok && bytes.byteLength <= MAX_PACKAGE_BYTES, bytes };
+};
 const parseJson = (bytes) => JSON.parse(new TextDecoder().decode(bytes));
 const integrityMatches = (bytes, release) => bytes.byteLength === Number(release.file_length) &&
     bytes.byteLength <= MAX_PACKAGE_BYTES &&

package/dist/application/NodeRuntimeCharacterizationService.js

@@ -0,0 +1,196 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { nodeCharacterizationExecutionInputSchema, nodeCharacterizationExecutionOutputSchema, nodeCharacterizationPreparationInputSchema, nodeCharacterizationPreparationOutputSchema, } from "../domain/nodeRuntimeCharacterization.js";
+import { AnalysisInputError, AnalysisProtocolError, ReplayPlanStaleError, } from "../domain/errors.js";
+import { createEvidence } from "../domain/evidence.js";
+import { controlledReplayOutputSchema } from "../domain/javascriptReplay.js";
+import { createRuntimeCharacterizationPlan, } from "../domain/runtimeCharacterization.js";
+import { err, ok } from "../domain/result.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { InstrumentedJavaScriptReplayHost } from "./InstrumentedJavaScriptReplayHost.js";
+import { runControlledReplayValidated, } from "./JavaScriptReplayService.js";
+const PREPARE_OPERATION = "prepare_node_characterization";
+const EXECUTE_OPERATION = "execute_node_characterization";
+const PROVIDER = {
+    id: "rea-node-characterization",
+    name: "REA Node runtime characterization",
+    version: "1",
+};
+/** Prepare exact Node/JavaScript characterization without executing target code. */
+export const prepareNodeCharacterization = async (dependencies, rawInput, options = {}) => {
+    const parsed = nodeCharacterizationPreparationInputSchema.safeParse(rawInput);
+    if (!parsed.success)
+        return err(new AnalysisInputError(PREPARE_OPERATION, { cause: parsed.error }));
+    const prepared = await prepareValidated(dependencies, parsed.data, options);
+    return prepared.ok
+        ? ok(jsonValueSchema.parse(nodeCharacterizationPreparationOutputSchema.parse(prepared.value)))
+        : prepared;
+};
+/** Execute only a freshly recomputed and separately approved characterization plan. */
+export const executeNodeCharacterization = async (dependencies, rawInput, options = {}) => {
+    const parsed = nodeCharacterizationExecutionInputSchema.safeParse(rawInput);
+    if (!parsed.success)
+        return err(new AnalysisInputError(EXECUTE_OPERATION, { cause: parsed.error }));
+    const prepared = await prepareValidated(dependencies, parsed.data.preparation, options);
+    if (!prepared.ok)
+        return prepared;
+    if (prepared.value.plan.plan_sha256 !== parsed.data.approved_plan_sha256)
+        return err(new ReplayPlanStaleError(parsed.data.approved_plan_sha256, prepared.value.plan.plan_sha256));
+    const plannedReplay = controlledReplayOutputSchema.parse(prepared.value.replay);
+    if (plannedReplay.phase !== "plan" || plannedReplay.plan === null)
+        return err(new AnalysisProtocolError("Node characterization preparation did not produce a replay plan"));
+    const host = new InstrumentedJavaScriptReplayHost(dependencies.host, parsed.data.preparation.instrumentation);
+    const executed = await runControlledReplayValidated({ ...dependencies, host }, {
+        ...parsed.data.preparation.replay,
+        mode: "execute",
+        approved: true,
+        plan_digest: plannedReplay.plan.plan_digest,
+    }, options);
+    if (!executed.ok)
+        return executed;
+    if (host.instrumentation === null)
+        return err(new AnalysisProtocolError("Node characterization execution omitted instrumentation evidence"));
+    return ok(jsonValueSchema.parse(nodeCharacterizationExecutionOutputSchema.parse({
+        schema_version: 1,
+        phase: "execution",
+        plan: prepared.value.plan,
+        transformation: host.instrumentation.manifest,
+        transformation_evidence: prepared.value.transformation_evidence,
+        evidence: createCharacterizationEvidence(prepared.value, controlledReplayOutputSchema.parse(executed.value)),
+        replay: controlledReplayOutputSchema.parse(executed.value),
+    })));
+};
+const prepareValidated = async (dependencies, input, options) => {
+    const host = new InstrumentedJavaScriptReplayHost(dependencies.host, input.instrumentation);
+    const replay = await runControlledReplayValidated({ ...dependencies, host }, input.replay, options);
+    if (!replay.ok)
+        return replay;
+    const output = controlledReplayOutputSchema.parse(replay.value);
+    if (output.phase !== "plan" ||
+        output.plan === null ||
+        host.instrumentation === null)
+        return err(new AnalysisProtocolError("Node characterization preparation omitted committed plan evidence"));
+    const module = output.plan.left.modules.find(({ alias }) => alias === input.selected_alias);
+    if (module === undefined)
+        return err(new AnalysisProtocolError("Node characterization replay plan omitted selected module"));
+    const plan = createCharacterizationPlan(input, host.instrumentation, output.plan);
+    return ok({
+        schema_version: 1,
+        phase: "preparation",
+        plan,
+        transformation: host.instrumentation.manifest,
+        transformation_evidence: createTransformationEvidence(input, host.instrumentation),
+        replay: output,
+    });
+};
+const createTransformationEvidence = (input, instrumentation) => createEvidence({
+    path: input.instrumentation.artifact_path,
+    sha256: input.instrumentation.artifact_sha256,
+    format: "javascript-bundle",
+}, PROVIDER, {
+    predicateType: "rea.javascript-export-transformation/v1",
+    operation: PREPARE_OPERATION,
+    parameters: {
+        selected_alias: input.selected_alias,
+        selected_sha256: input.instrumentation.selection.selected_sha256,
+    },
+    result: jsonValueSchema.parse(instrumentation.manifest),
+    confidence: "derived",
+    authority: "shipped-artifact",
+    locations: [
+        {
+            kind: "file-offset-range",
+            start: input.instrumentation.selection.byte_start,
+            end: input.instrumentation.selection.byte_end,
+        },
+    ],
+    limitations: [
+        "The transformation is deterministic derived evidence; execution authority is established only by a separately approved characterization run.",
+    ],
+});
+const createCharacterizationEvidence = (prepared, replay) => {
+    if (replay.phase !== "execute" || replay.evidence === null)
+        throw new AnalysisProtocolError("Node characterization execution omitted replay Evidence");
+    return createEvidence({
+        path: prepared.plan.artifact.path,
+        sha256: prepared.plan.artifact.sha256,
+        format: "javascript-bundle",
+    }, PROVIDER, {
+        predicateType: "rea.runtime-characterization/v1",
+        operation: EXECUTE_OPERATION,
+        parameters: {
+            plan_sha256: prepared.plan.plan_sha256,
+            replay_evidence_id: replay.evidence.evidence_id,
+        },
+        result: jsonValueSchema.parse({
+            plan: prepared.plan,
+            transformation_evidence_id: prepared.transformation_evidence.evidence_id,
+            replay_evidence_id: replay.evidence.evidence_id,
+            execution: replay.evidence.normalized_result,
+        }),
+        confidence: "observed",
+        authority: "controlled-replay",
+        environment: replay.evidence.environment,
+        limitations: [
+            "This Evidence proves only the finite approved characterization plan and transformed controlled-replay authority, not unmodified shipped-runtime equivalence.",
+            ...replay.evidence.limitations,
+        ],
+        evidenceLinks: [
+            prepared.transformation_evidence.evidence_id,
+            replay.evidence.evidence_id,
+        ],
+    });
+};
+const createCharacterizationPlan = (input, instrumentation, replayPlan) => createRuntimeCharacterizationPlan({
+    schema_version: 1,
+    preparation_sha256: digestPreparation(instrumentation.manifest.instrumented_sha256, replayPlan.plan_digest),
+    artifact: {
+        path: input.instrumentation.artifact_path,
+        sha256: input.instrumentation.artifact_sha256,
+        byte_length: instrumentation.manifest.original_byte_length,
+    },
+    runtime: {
+        family: "ecmascript",
+        provider_id: "node-javascript",
+        executable_path: replayPlan.runtime.executable.path,
+        executable_sha256: replayPlan.runtime.executable.sha256,
+        version: replayPlan.runtime.executable.version,
+        profile_sha256: replayPlan.policy_sha256,
+    },
+    callable: {
+        callable_id: `callable/${input.instrumentation.selection.selected_sha256}`,
+        module_id: stableModuleId(input.selected_alias),
+        export_name: input.instrumentation.selection.export_name,
+        semantic_evidence_id: null,
+        selector_sha256: input.instrumentation.selection.selected_sha256,
+    },
+    working_directory: "/work",
+    isolated_home: "/work",
+    expected_effect: input.expected_effect,
+    allowed_boundaries: [],
+    limits: {
+        max_calls: replayPlan.cases.length,
+        max_processes: 0,
+        max_files: 0,
+        max_bytes: replayPlan.limits.output_bytes,
+        max_handles: replayPlan.limits.tasks,
+        timeout_ms: replayPlan.limits.wall_time_ms,
+        idle_timeout_ms: replayPlan.limits.wall_time_ms,
+    },
+    determinism: {
+        clock: "fixed",
+        randomness: "seeded",
+        identifiers: "deterministic",
+        seed: replayPlan.determinism.random_seed,
+    },
+    authority: {
+        preparation_approved: true,
+        execution_approved: false,
+        network: "none",
+        provider_owned_process_only: true,
+    },
+});
+const digestPreparation = (instrumentedSha256, replayPlanDigest) => createHash("sha256")
+    .update(`rea.node-characterization-preparation/v1\0${instrumentedSha256}\0${replayPlanDigest}`)
+    .digest("hex");
+const stableModuleId = (alias) => `module/${createHash("sha256").update(alias).digest("hex")}`;

package/dist/application/PermissionAuthority.js

@@ -73,31 +73,52 @@ const errorReason = (error) => isNotFound(error) ? "not_found" : "io";
 /** Stateful owner for permission evaluation, consumption, reload, and revoke. */
 export class PermissionAuthority {
     policy;
-    constructor(policy) {
+    configuredAuthority;
+    constructor(policy, configuredAuthority) {
         this.policy = policy;
+        this.configuredAuthority = configuredAuthority;
+    }
+    /** Create a connection-owned overlay for once and session grants. */
+    createConnectionAuthority() {
+        return new PermissionAuthority(createPermissionPolicy([]), this.configuredAuthority ?? this);
     }
     /** Canonicalize and authorize one exact operation before its side effect. */
     async authorize(request, access, options = {}) {
-        const evaluated = await this.explain(request, access, options);
+        const evaluated = await this.evaluateRequest(request, access, options);
         if (!evaluated.ok)
             return evaluated;
-        const decision = evaluated.value;
-        this.policy = consumePermission(this.policy, decision);
-        return ok(decision);
+        const { decision, owner, request: canonicalRequest } = evaluated.value;
+        owner.policy = consumePermission(owner.policy, decision);
+        return ok({ ...decision, request: canonicalRequest });
     }
     /** Dry-run the exact shared evaluation without consuming a once grant. */
     async explain(request, access, options = {}) {
+        const evaluated = await this.evaluateRequest(request, access, options);
+        return evaluated.ok
+            ? ok({
+                ...evaluated.value.decision,
+                request: evaluated.value.request,
+            })
+            : evaluated;
+    }
+    async evaluateRequest(request, access, options) {
         const canonical = await canonicalizePermissionRequest(request, access);
         if (!canonical.ok)
             return canonical;
-        const decision = evaluatePermission(this.policy, canonical.value);
-        if (!decision.allowed)
-            return err(new PermissionRequiredError(canonical.value, decision.missing, ceilingFor(this.policy, canonical.value.capability), options.elicitationSupported ?? false, options.restartRequired ?? false));
-        return ok({ ...decision, request: canonical.value });
+        const evaluated = this.evaluateCanonical(canonical.value, options);
+        return evaluated.ok
+            ? ok({ ...evaluated.value, request: canonical.value })
+            : evaluated;
     }
     /** Add authority beneath the administrator ceiling. */
     grant(grant) {
-        const result = grantPermission(this.policy, grant);
+        const policy = this.configuredAuthority === undefined
+            ? this.policy
+            : {
+                ...this.policy,
+                ceilings: this.configuredAuthority.effectivePolicy().ceilings,
+            };
+        const result = grantPermission(policy, grant);
         if (result.ok)
             this.policy = result.value;
         return result;
@@ -110,44 +131,61 @@ export class PermissionAuthority {
     clearSessionGrants() {
         this.policy = clearSessionPermissions(this.policy);
     }
-    /** Atomically replace optional persisted project grants. */
-    async replaceProjectGrants(grants) {
-        let candidate = {
-            ...this.policy,
-            grants: this.policy.grants.filter(({ lifetime }) => lifetime !== "project"),
+    effectivePolicy() {
+        if (this.configuredAuthority === undefined)
+            return this.policy;
+        const configured = this.configuredAuthority.effectivePolicy();
+        return {
+            ceilings: configured.ceilings,
+            grants: [...configured.grants, ...this.policy.grants],
+            revoked_grant_ids: new Set([
+                ...configured.revoked_grant_ids,
+                ...this.policy.revoked_grant_ids,
+            ]),
+            consumed_grant_ids: new Set([
+                ...configured.consumed_grant_ids,
+                ...this.policy.consumed_grant_ids,
+            ]),
         };
-        for (const grant of grants) {
-            const canonical = await canonicalizeGrant(grant);
-            if (!canonical.ok)
-                return canonical;
-            const added = grantPermission(candidate, canonical.value);
-            if (!added.ok)
-                return err(new PermissionPathError(grant.grant_id, "io", {
-                    cause: added.error,
-                }));
-            candidate = added.value;
+    }
+    evaluateCanonical(request, options) {
+        const configured = this.configuredAuthority;
+        if (configured !== undefined) {
+            const configuredDecision = evaluatePermission(configured.effectivePolicy(), request);
+            if (configuredDecision.allowed)
+                return ok({ decision: configuredDecision, owner: configured });
         }
-        this.policy = candidate;
-        return ok(null);
+        const localPolicy = configured === undefined
+            ? this.policy
+            : { ...this.policy, ceilings: configured.effectivePolicy().ceilings };
+        const localDecision = evaluatePermission(localPolicy, request);
+        if (localDecision.allowed)
+            return ok({ decision: localDecision, owner: this });
+        const effective = this.effectivePolicy();
+        const denied = evaluatePermission(effective, request);
+        if (denied.allowed)
+            return ok({ decision: denied, owner: this });
+        return err(new PermissionRequiredError(request, denied.missing, ceilingFor(effective, request.capability), options.elicitationSupported ?? false, options.restartRequired ?? false));
+    }
+    /** Atomically replace optional persisted project grants. */
+    async replaceProjectGrants(grants) {
+        return this.replaceGrants(grants, "project");
     }
     /** Replace grants derived from the currently loaded administrator ceiling. */
     async replaceAdministratorGrants(grants) {
-        let candidate = {
+        return this.replaceGrants(grants, "administrator");
+    }
+    async replaceGrants(grants, lifetime) {
+        const canonical = await canonicalizeGrants(grants);
+        if (!canonical.ok)
+            return canonical;
+        const replaced = addGrantsToPolicy({
             ...this.policy,
-            grants: this.policy.grants.filter(({ lifetime }) => lifetime !== "administrator"),
-        };
-        for (const grant of grants) {
-            const canonical = await canonicalizeGrant(grant);
-            if (!canonical.ok)
-                return canonical;
-            const added = grantPermission(candidate, canonical.value);
-            if (!added.ok)
-                return err(new PermissionPathError(grant.grant_id, "io", {
-                    cause: added.error,
-                }));
-            candidate = added.value;
-        }
-        this.policy = candidate;
+            grants: this.policy.grants.filter((grant) => grant.lifetime !== lifetime),
+        }, canonical.value);
+        if (!replaced.ok)
+            return replaced;
+        this.policy = replaced.value;
         return ok(null);
     }
     /** Atomically replace reloadable ceilings and persisted grants. */
@@ -155,29 +193,20 @@ export class PermissionAuthority {
         const ceilings = await canonicalizePermissionCeilings(configuration.ceilings);
         if (!ceilings.ok)
             return ceilings;
-        const grants = [];
-        for (const grant of [
+        const grants = await canonicalizeGrants([
             ...configuration.administratorGrants,
             ...configuration.projectGrants,
-        ]) {
-            const canonical = await canonicalizeGrant(grant);
-            if (!canonical.ok)
-                return canonical;
-            grants.push(canonical.value);
-        }
-        let candidate = {
+        ]);
+        if (!grants.ok)
+            return grants;
+        const candidate = {
             ...reloadPermissionCeilings(this.policy, ceilings.value),
             grants: this.policy.grants.filter(({ lifetime }) => lifetime !== "administrator" && lifetime !== "project"),
         };
-        for (const grant of grants) {
-            const added = grantPermission(candidate, grant);
-            if (!added.ok)
-                return err(new PermissionPathError(grant.grant_id, "io", {
-                    cause: added.error,
-                }));
-            candidate = added.value;
-        }
-        this.policy = candidate;
+        const replaced = addGrantsToPolicy(candidate, grants.value);
+        if (!replaced.ok)
+            return replaced;
+        this.policy = replaced.value;
         return ok(null);
     }
     /** Replace ceilings without restarting the MCP process. */
@@ -194,17 +223,31 @@ export const createPermissionAuthority = async (ceilings, grants = []) => {
     const canonical = await canonicalizePermissionCeilings(ceilings);
     if (!canonical.ok)
         return canonical;
-    let policy = createPermissionPolicy(canonical.value);
+    const canonicalGrants = await canonicalizeGrants(grants);
+    if (!canonicalGrants.ok)
+        return canonicalGrants;
+    const policy = addGrantsToPolicy(createPermissionPolicy(canonical.value), canonicalGrants.value);
+    return policy.ok ? ok(new PermissionAuthority(policy.value)) : policy;
+};
+const canonicalizeGrants = async (grants) => {
+    const canonical = [];
     for (const grant of grants) {
         const canonicalGrant = await canonicalizeGrant(grant);
         if (!canonicalGrant.ok)
             return canonicalGrant;
-        const added = grantPermission(policy, canonicalGrant.value);
+        canonical.push(canonicalGrant.value);
+    }
+    return ok(canonical);
+};
+const addGrantsToPolicy = (initial, grants) => {
+    let policy = initial;
+    for (const grant of grants) {
+        const added = grantPermission(policy, grant);
         if (!added.ok)
             return err(new PermissionPathError(grant.grant_id, "io", { cause: added.error }));
         policy = added.value;
     }
-    return ok(new PermissionAuthority(policy));
+    return ok(policy);
 };
 const canonicalizeGrant = async (grant) => {
     const scope = await canonicalizeScope(grant, "read");

package/dist/application/ProcessCaptureCapability.js

@@ -1,8 +1,8 @@
 import { tmpdir } from "node:os";
-import { spawn } from "node-pty";
 /** Probe the actual native PTY seam instead of inferring support from the OS name. */
 export const probeProcessCaptureCapability = async () => {
     try {
+        const { spawn } = await import("@lydell/node-pty");
         const terminal = spawn(process.platform === "win32" ? "cmd.exe" : "/bin/sh", process.platform === "win32" ? ["/c", "exit", "0"] : ["-c", "exit 0"], {
             cwd: tmpdir(),
             env: { HOME: tmpdir(), TERM: "xterm-256color" },

package/dist/application/ProcessCapturePermission.js

@@ -0,0 +1,13 @@
+/** Build the exact permission request shared by process-capture adapters. */
+export const processCapturePermissionRequest = (scenario) => ({
+    capability: "process_capture",
+    roots: [scenario.working_directory, ...scenario.filesystem_roots],
+    executables: [scenario.executable],
+    environment_names: [
+        ...Object.keys(scenario.environment),
+        ...scenario.inherit_environment,
+    ],
+    network: scenario.network_access === "host" ? "external" : "none",
+    mount: false,
+    operation_identity: `capture_process_scenario:${scenario.executable}`,
+});

package/dist/application/ProcessCli.js

@@ -5,6 +5,7 @@ import { createEvidence, parseEvidence } from "../domain/evidence.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { compareProcessCaptures, LEGACY_PROCESS_CAPTURE_MESSAGE, parseProcessScenario, parseProcessCapture, } from "../domain/processCapture.js";
 import { captureProcessScenario } from "./ProcessHarness.js";
+import { processCapturePermissionRequest } from "./ProcessCapturePermission.js";
 import { PROCESS_PROVIDER, createProcessCaptureEvidence, } from "./ProcessEvidence.js";
 import { loadConfiguredPermissionAuthority } from "./PermissionConfiguration.js";
 const MAX_INPUT_BYTES = 64 * 1024 * 1024;
@@ -25,18 +26,7 @@ export const captureProcessScenarioFile = async (path) => {
         const authority = await loadConfiguredPermissionAuthority(config.value);
         if (!authority.ok)
             return cliAnalysisError(authority.error);
-        const authorized = await authority.value.authorize({
-            capability: "process_capture",
-            roots: [scenario.working_directory, ...scenario.filesystem_roots],
-            executables: [scenario.executable],
-            environment_names: [
-                ...Object.keys(scenario.environment),
-                ...scenario.inherit_environment,
-            ],
-            network: scenario.network_access === "host" ? "external" : "none",
-            mount: false,
-            operation_identity: `capture_process_scenario:${scenario.executable}`,
-        }, "read");
+        const authorized = await authority.value.authorize(processCapturePermissionRequest(scenario), "read");
         if (!authorized.ok)
             return cliAnalysisError(authorized.error instanceof PermissionRequiredError
                 ? authorized.error

package/dist/application/ProcessHarness.js

@@ -1,4 +1,3 @@
-import { spawn } from "node-pty";
 import { validateProcessCapture } from "../domain/processCapture.js";
 import { err, ok } from "../domain/result.js";
 import { ProcessCaptureError, processCaptureCancelled, } from "./ProcessCaptureError.js";
@@ -111,6 +110,7 @@ const startCaptureRuntime = async (options) => {
     let shimReplay;
     let terminal;
     try {
+        const { spawn } = await import("@lydell/node-pty");
         replay = await startLoopbackReplay(scenario);
         const startedAt = new Date();
         const started = Date.now();

package/dist/application/ProcessPairedExperiment.js

@@ -0,0 +1,72 @@
+import { processCaptureCancelled, } from "./ProcessCaptureError.js";
+import { captureProcessScenario } from "./ProcessHarness.js";
+import { compareProcessCaptures } from "../domain/processComparison.js";
+import { PROCESS_COMPARISON_DIMENSIONS } from "../domain/processComparison.js";
+import { analyzeProcessRepeatability, bindProcessScenario, } from "../domain/processPairedExperiment.js";
+import { err, ok } from "../domain/result.js";
+const productionCapturePort = {
+    capture: captureProcessScenario,
+};
+const captureRepeats = async (input) => {
+    const captures = [];
+    for (let index = 0; index < input.repeatCount; index += 1) {
+        if (input.signal?.aborted === true)
+            return err(processCaptureCancelled());
+        const capture = await input.port.capture(input.scenario, input.policy, input.signal);
+        if (!capture.ok)
+            return err(capture.error);
+        captures.push(capture.value);
+    }
+    return ok(captures);
+};
+/** Execute repeatability-first authority/candidate captures under one contract. */
+export const runPairedProcessExperiment = async (experiment, policy, options = {}) => {
+    const port = options.capturePort ?? productionCapturePort;
+    const authorityScenario = bindProcessScenario(experiment.shared_scenario, experiment.authority);
+    const candidateScenario = bindProcessScenario(experiment.shared_scenario, experiment.candidate);
+    const authorityRuns = await captureRepeats({
+        scenario: authorityScenario,
+        repeatCount: experiment.repeat_count,
+        policy,
+        port,
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+    if (!authorityRuns.ok)
+        return authorityRuns;
+    const candidateRuns = await captureRepeats({
+        scenario: candidateScenario,
+        repeatCount: experiment.repeat_count,
+        policy,
+        port,
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+    if (!candidateRuns.ok)
+        return candidateRuns;
+    const authorityRepeatability = analyzeProcessRepeatability(authorityRuns.value, experiment.required_dimensions);
+    const candidateRepeatability = analyzeProcessRepeatability(candidateRuns.value, experiment.required_dimensions);
+    const stable = authorityRepeatability.stable && candidateRepeatability.stable;
+    const allDimensionsRequired = PROCESS_COMPARISON_DIMENSIONS.every((dimension) => experiment.required_dimensions.includes(dimension));
+    const authorityLatest = authorityRuns.value.at(-1);
+    const candidateLatest = candidateRuns.value.at(-1);
+    const crossSide = stable &&
+        allDimensionsRequired &&
+        authorityLatest !== undefined &&
+        candidateLatest !== undefined
+        ? compareProcessCaptures(authorityLatest, candidateLatest, {
+            maxCaptureAgeMs: experiment.freshness_policy.max_capture_age_ms,
+            ...(options.now === undefined ? {} : { now: options.now }),
+        })
+        : null;
+    return ok({
+        authority_runs: authorityRuns.value,
+        candidate_runs: candidateRuns.value,
+        authority_repeatability: authorityRepeatability,
+        candidate_repeatability: candidateRepeatability,
+        cross_side: crossSide,
+        cross_side_blocked_reason: crossSide !== null
+            ? null
+            : !allDimensionsRequired
+                ? "Cross-side comparison is blocked until every returned dimension is required and repeatable."
+                : "Cross-side comparison is blocked because a required same-side dimension is unstable.",
+    });
+};