@descryy/runtime-orchestrator 0.0.0

package/dist/instrumented-execution.js

@@ -0,0 +1,363 @@
+/**
+ * **The assembly nothing else performed.**
+ *
+ * Every piece of the runtime existed and none of them were wired together
+ * in production code: the controller spawned services, `RuntimeAdapter`
+ * could build collectors, `resolveServiceRootForOrigin` could map an origin
+ * to a source root, and `EvidenceStore` could persist. Only tests ever
+ * connected them, each in its own way, which meant the thing the product
+ * actually does had no single implementation to be right or wrong.
+ *
+ * This module is that implementation. It:
+ *
+ * 1. runs an `ExecutionController` over a `services` configuration;
+ * 2. wraps each spawned process in a **live** `ProcessOutputSource` that
+ *    polls the accumulated buffer and yields each line exactly once;
+ * 3. builds a `CollectorContext` carrying a real `resolveSourceRoot`,
+ *    closed over the execution's own processes — the channel RT-033 added
+ *    and RT-029 built the lookup for, which until now nothing populated;
+ * 4. starts the adapter's collectors, drains them, stops them;
+ * 5. writes every emitted item through `EvidenceStore`, so redaction runs
+ *    rather than being assumed (plan §28).
+ *
+ * **What it deliberately does not do.** It does not decide whether a
+ * finding exists, does not correlate to graph nodes, and does not drive a
+ * browser. Those are separate stages with separate contracts, and folding
+ * them in here would make the one place that assembles the runtime also the
+ * place that judges it.
+ */
+import { resolveServiceRootForOrigin } from "@descryy/runtime-contracts";
+import { createInboundProxy } from "@descryy/runtime-backend-observation";
+import { ExecutionController, checkDependencyVersions, checkEnvironmentVersion, } from "@descryy/runtime-controller";
+import { EvidenceStore } from "@descryy/runtime-evidence-store";
+import { createPollingProcessOutputSource } from "./polling-output-source.js";
+import { COLLECTOR_VERSION } from "./collector-version.js";
+/**
+ * Builds the origin → source-root lookup a collector reads through
+ * `CollectorContext.resolveSourceRoot`.
+ *
+ * This is the piece that had been missing at both ends: RT-029 wrote the
+ * lookup and nothing called it; RT-033 added the channel and nothing filled
+ * it. It closes over the execution's *own* processes, which is what makes
+ * the port→service join possible at all — under ephemeral ports the
+ * configuration cannot know the port, so only the running process can say.
+ */
+export function createSourceRootResolver(processes, configuration) {
+    return (origin) => resolveServiceRootForOrigin(origin, { processes, configuration });
+}
+export async function runInstrumentedExecution(input) {
+    const configuration = input.execution.configuration;
+    const controller = ExecutionController.create(input.execution);
+    // Closes §34's remaining "runtime self-observability" gap after RT-219:
+    // `controller.run()` has exactly one throw path (`controller.ts`'s own
+    // `spawnProcess` catch/rethrow, after it has already recorded the
+    // failure in `serviceStartResults` and transitioned to `FAILED_START`) --
+    // left unguarded here, that throw used to reject this whole function,
+    // uncaught, the identical "harness machinery breaks, zero evidence
+    // trail" shape RT-219 already fixed one layer up for `collector.start()`.
+    // Caught the same way: written through the same `EvidenceStore`, tagged
+    // `source: "harness"`. `controller.execution` and
+    // `controller.serviceStartResults` are both real at this point (`run()`
+    // mutates its private state, including a call to its own `#finish()`,
+    // before it ever throws) so the run resolves with what actually happened
+    // rather than rejecting the caller's own promise -- the same "resolves
+    // normally" contract RT-219 already established.
+    let execution;
+    try {
+        execution = await controller.run(input.runOptions);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+        const harnessEvidence = input.store.write({
+            executionId: controller.execution.executionId,
+            timestamp: new Date().toISOString(),
+            source: "harness",
+            service: null,
+            process: null,
+            eventType: "COLLECTOR_ERROR",
+            payload: {
+                raw: `ExecutionController.run() threw instead of resolving: ${detail}`,
+                error: detail,
+            },
+            traceId: null,
+            requestId: null,
+            correlationId: null,
+            graphNodeId: null,
+            sourceLocation: null,
+            stackTrace: null,
+            confidence: 1,
+            collectorVersion: COLLECTOR_VERSION,
+        });
+        return {
+            execution: controller.execution,
+            evidence: [harnessEvidence],
+            collectorCapabilities: [],
+            validationError: `ExecutionController.run() threw: ${detail}`,
+        };
+    }
+    if (controller.validationError !== null) {
+        return { execution, evidence: [], collectorCapabilities: [], validationError: controller.validationError };
+    }
+    // One source per spawned service. `serviceName` is what joins a handle
+    // back to its configuration entry, and a handle without one cannot be
+    // attributed -- skipped rather than guessed at.
+    // Declared before the sources close over it: each generator polls until
+    // this flips, and the flip is what lets `stop()` finish rather than wait
+    // forever on a source still watching a live buffer.
+    let finished = false;
+    const sources = [];
+    for (const handle of execution.processes) {
+        if (handle.serviceName === null)
+            continue;
+        const serviceName = handle.serviceName;
+        sources.push(createPollingProcessOutputSource({
+            processId: handle.processId,
+            readOutput: () => controller.readProcessOutput(serviceName),
+            isFinished: () => finished,
+        }));
+    }
+    const backendCollectors = input.adapter.createBackendCollectors(sources);
+    const emitted = [];
+    // `DEC-NEXT-fault-layer-empirical-confirmation.md`'s `dependency`/
+    // `environment` mechanisms -- the producer side of the same shape RT-219
+    // established for `automation` above: a structural fact the runtime
+    // establishes about its own execution environment, tagged
+    // `source: "dependency-check"` / `"environment-check"` rather than the
+    // service's own domain source, so a reader can tell "the project's
+    // declared versions don't match what actually ran" from an observation of
+    // the application itself without inspecting payload text. Run once per
+    // spawned service (each has its own `cwd`, and therefore potentially its
+    // own lockfile/`engines.node`), unconditionally -- "cheap, always
+    // available, no rerun needed" per the ruling -- but only ever emitted as
+    // evidence when an actual mismatch is found, the same "silence must not
+    // manufacture evidence" discipline `"harness"` already observes.
+    //
+    // The observed Node version is `execution.environmentMetadata`'s own
+    // `nodeVersion` -- `process.version` of the controller process, captured
+    // once by `captureEnvironmentMetadata` during `controller.run()` above,
+    // never re-probed here. It is non-null whenever `validationError` is
+    // null (the early return above already excluded the one case where it
+    // would not be).
+    const observedNodeVersion = execution.environmentMetadata?.nodeVersion ?? process.version;
+    for (const handle of execution.processes) {
+        if (handle.serviceName === null)
+            continue;
+        const serviceConfig = configuration.services[handle.serviceName];
+        if (serviceConfig === undefined)
+            continue;
+        const dependencyResult = checkDependencyVersions(serviceConfig.cwd);
+        for (const mismatch of dependencyResult.mismatches) {
+            emitted.push(input.store.write({
+                executionId: execution.executionId,
+                timestamp: new Date().toISOString(),
+                source: "dependency-check",
+                service: handle.serviceName,
+                process: handle.processId,
+                eventType: "DEPENDENCY_VERSION_MISMATCH",
+                payload: {
+                    raw: `dependency "${mismatch.name}": lockfile declares ${mismatch.declaredVersion}, resolved ${mismatch.resolvedVersion}`,
+                    name: mismatch.name,
+                    declaredVersion: mismatch.declaredVersion,
+                    resolvedVersion: mismatch.resolvedVersion,
+                },
+                traceId: null,
+                requestId: null,
+                correlationId: null,
+                graphNodeId: null,
+                sourceLocation: null,
+                stackTrace: null,
+                confidence: 1,
+                collectorVersion: COLLECTOR_VERSION,
+            }));
+        }
+        const environmentResult = checkEnvironmentVersion(serviceConfig.cwd, observedNodeVersion);
+        if (environmentResult.mismatch) {
+            emitted.push(input.store.write({
+                executionId: execution.executionId,
+                timestamp: new Date().toISOString(),
+                source: "environment-check",
+                service: handle.serviceName,
+                process: handle.processId,
+                eventType: "ENVIRONMENT_VERSION_MISMATCH",
+                payload: {
+                    raw: `declared node version ${environmentResult.declaredVersion ?? "unknown"} (${environmentResult.declaredSource ?? "unknown"}), observed ${environmentResult.observedVersion}`,
+                    declaredVersion: environmentResult.declaredVersion,
+                    declaredSource: environmentResult.declaredSource,
+                    observedVersion: environmentResult.observedVersion,
+                },
+                traceId: null,
+                requestId: null,
+                correlationId: null,
+                graphNodeId: null,
+                sourceLocation: null,
+                stackTrace: null,
+                confidence: 1,
+                collectorVersion: COLLECTOR_VERSION,
+            }));
+        }
+    }
+    // Opt-in InboundProxy wiring (RT-192, DEC-271) -- see `frontWithInboundProxy`'s
+    // own doc for what this does and, just as important, what it does not
+    // close. Built AFTER `controller.run()` has already returned, so every
+    // service's own readiness answer already exists in
+    // `controller.serviceStartResults` -- this loop reads that answer, it
+    // never re-derives or re-checks it itself.
+    const proxies = [];
+    if (input.frontWithInboundProxy !== undefined) {
+        for (const handle of execution.processes) {
+            const serviceName = handle.serviceName;
+            if (serviceName === null)
+                continue;
+            if (input.frontWithInboundProxy[serviceName] !== true)
+                continue;
+            const readinessOutcome = controller.serviceStartResults.find((result) => result.serviceName === serviceName && result.stage === "readiness");
+            if (readinessOutcome?.succeeded !== true || handle.port === null) {
+                // Requested but never proven live -- reported as a real
+                // COLLECTOR_ERROR, the same shape every other unavailable collector
+                // in this function gets, rather than a silent no-proxy fallback
+                // ("we did not observe this" vs "there was nothing to observe",
+                // plan §17, applies here too).
+                emitted.push(input.store.write({
+                    executionId: execution.executionId,
+                    timestamp: new Date().toISOString(),
+                    source: "backend-process",
+                    service: serviceName,
+                    process: handle.processId,
+                    eventType: "COLLECTOR_ERROR",
+                    payload: {
+                        raw: `service "${serviceName}" was flagged frontWithInboundProxy but its own readiness never succeeded -- never fronting a process that was not proven live`,
+                        collectorId: `inbound-proxy:${handle.processId}`,
+                    },
+                    traceId: null,
+                    requestId: null,
+                    correlationId: null,
+                    graphNodeId: null,
+                    sourceLocation: null,
+                    stackTrace: null,
+                    confidence: 1,
+                    collectorVersion: COLLECTOR_VERSION,
+                }));
+                continue;
+            }
+            proxies.push({
+                serviceName,
+                proxy: createInboundProxy({
+                    targetHost: "127.0.0.1",
+                    targetPort: handle.port,
+                    processId: handle.processId,
+                    service: serviceName,
+                }),
+            });
+        }
+    }
+    const collectors = [...backendCollectors, ...proxies.map((entry) => entry.proxy.collector)];
+    const context = {
+        executionId: execution.executionId,
+        configuration,
+        // Redaction runs here, on the way in -- EvidenceStore.write() is the
+        // only path that sets redactionStatus, so nothing reaches the returned
+        // array without having been through it (plan §28).
+        emit: (evidenceInput) => {
+            emitted.push(input.store.write({ ...evidenceInput, executionId: execution.executionId }));
+        },
+        resolveSourceRoot: createSourceRootResolver(execution.processes, configuration),
+    };
+    // RT-219 (runtime self-observability). `collector.start()`'s documented
+    // failure path resolves `{available: false, reason}` -- the loop below
+    // already reports that one, tagged with the domain source the collector
+    // was going to observe. A collector that instead THROWS out of start()
+    // is a different claim: not "I looked and could not," but the harness's
+    // own machinery breaking before it ever got that far. Left unguarded,
+    // that throw rejects this Promise.all and `runInstrumentedExecution`
+    // aborts uncaught -- zero evidence trail for why, the exact "collector
+    // failure mistaken for absence of failure" shape plan §17 forbids,
+    // applied to the harness's own code instead of the application's.
+    // Caught here and written through the same EvidenceStore, tagged
+    // `source: "harness"` rather than the collector's domain source, so a
+    // reader can tell "our own observer broke" from "the observed system
+    // did" without inspecting payload text.
+    const startOutcomes = await Promise.all(collectors.map(async (collector) => {
+        try {
+            return { collector, result: await collector.start(context), threw: false };
+        }
+        catch (error) {
+            const detail = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+            emitted.push(input.store.write({
+                executionId: execution.executionId,
+                timestamp: new Date().toISOString(),
+                source: "harness",
+                service: null,
+                process: null,
+                eventType: "COLLECTOR_ERROR",
+                payload: {
+                    raw: `collector "${collector.collectorId}" threw during start() instead of resolving {available:false}: ${detail}`,
+                    collectorId: collector.collectorId,
+                    error: detail,
+                },
+                traceId: null,
+                requestId: null,
+                correlationId: null,
+                graphNodeId: null,
+                sourceLocation: null,
+                stackTrace: null,
+                confidence: 1,
+                collectorVersion: COLLECTOR_VERSION,
+            }));
+            return { collector, result: { available: false, reason: `start() threw: ${detail}` }, threw: true };
+        }
+    }));
+    // A thrown start() was already reported above, under `source: "harness"`
+    // -- excluded here so it is not reported a second time under
+    // `source: "backend-process"` by the loop below, which would collide
+    // the two tags on what is really one failure.
+    const unavailable = startOutcomes.filter((entry) => !entry.threw && !entry.result.available);
+    // A collector that could not start is reported, never silently absent:
+    // "we did not observe this" and "there was nothing to observe" are
+    // different claims (plan §17).
+    for (const entry of unavailable) {
+        emitted.push(input.store.write({
+            executionId: execution.executionId,
+            timestamp: new Date().toISOString(),
+            source: "backend-process",
+            service: null,
+            process: null,
+            eventType: "COLLECTOR_ERROR",
+            payload: {
+                raw: `collector "${entry.collector.collectorId}" reported unavailable at start: ${entry.result.available ? "" : (entry.result.reason ?? "no reason given")}`,
+                collectorId: entry.collector.collectorId,
+            },
+            traceId: null,
+            requestId: null,
+            correlationId: null,
+            graphNodeId: null,
+            sourceLocation: null,
+            stackTrace: null,
+            confidence: 1,
+            collectorVersion: COLLECTOR_VERSION,
+        }));
+    }
+    // Every fronted proxy that actually started (a collector reported
+    // `available: false` above never reaches here -- its port stayed null on
+    // that codepath, matching `InboundProxy.port()`'s own contract).
+    const proxyPorts = {};
+    for (const entry of proxies) {
+        const port = entry.proxy.port();
+        if (port !== null)
+            proxyPorts[entry.serviceName] = port;
+    }
+    await input.onReady?.({ execution, proxyPorts });
+    await new Promise((resolve) => setTimeout(resolve, input.observeForMs));
+    // Order matters: the sources must be told the process is done before
+    // stop() awaits their drain, or stop() waits forever on a generator
+    // still polling a live buffer.
+    finished = true;
+    await Promise.all(collectors.map((collector) => collector.stop()));
+    await controller.stop();
+    return {
+        execution: controller.execution,
+        evidence: emitted,
+        collectorCapabilities: collectors.map((collector) => ({ collectorId: collector.collectorId, capabilities: collector.capabilities() })),
+        validationError: null,
+    };
+}
+//# sourceMappingURL=instrumented-execution.js.map

package/dist/instrumented-execution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumented-execution.js","sourceRoot":"","sources":["../src/instrumented-execution.ts"],"names":[],"mappings":"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"}

package/dist/jvm-agent/build.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Compiles `Agent.java` into `agent.jar` and `Attacher.java` into
+ * `Attacher.class`, once, and only when the source is newer than the build
+ * output — the same mtime-cache rule `kotlin-server/build.ts` (test fixture
+ * side) already uses, applied here to shipped `src/` code instead of a test
+ * fixture, because the agent and its launcher are real product code:
+ * `attach-to-running-jvm-process.ts` runs the compiled artifacts, it does
+ * not compile them itself at call time.
+ *
+ * **`tools.jar` is JDK-8-only.** `com.sun.tools.attach.VirtualMachine`
+ * shipped inside `tools.jar` through JDK 8; from JDK 9 it moved into the
+ * `jdk.attach` module and is resolvable on the classpath with no extra jar.
+ * `findToolsJarIfPresent` looks for it and returns `null` when absent
+ * (JDK 9+, or a JRE with no `tools.jar` at all) — `Attacher.java` is then
+ * compiled and later run with no extra classpath entry, which is correct
+ * for JDK 9+ but has only been exercised against JDK 8 on this machine (the
+ * only JDK installed here); see this module's own decisions-inbox entry for
+ * that disclosed gap.
+ *
+ * **ByteBuddy, vendored the same way `junit-platform-console-standalone` is
+ * for the JUnit reporter** (`packages/test-runner/reporters/junit/build.mjs`):
+ * one pinned version, fetched once from Maven Central, checksum-verified,
+ * cached beside the agent's own sources — never a build tool. `Agent.java`
+ * needs a real bytecode-manipulation library for `DispatcherServlet`
+ * method-entry advice (RT-201); hand-written raw ASM/bytecode patching for
+ * that is not realistic, and Maven/Gradle here would mean resolving a
+ * dependency tree for one library this single file uses. The plain
+ * `net.bytebuddy:byte-buddy` artifact (not `byte-buddy-dep`) is used
+ * specifically because it repackages its own ASM under
+ * `net.bytebuddy.jar.asm.*` (verified directly against this exact jar,
+ * `unzip -l`) — one self-contained jar, no second dependency to vendor.
+ * `Class-Path: byte-buddy-<version>.jar` in `MANIFEST.MF` is a **static,
+ * version-pinned line** rather than a generated one, so a version bump is a
+ * two-line, reviewable diff (URL/digest here, `Class-Path` in the manifest)
+ * exactly like `junit-platform-console-standalone`'s. It sits beside
+ * `agent.jar` in the same directory as `Agent.java` itself (below) because
+ * the JDK resolves an agent JAR's `Class-Path` manifest entries relative to
+ * the agent JAR's own location, for both `-javaagent` and
+ * `VirtualMachine.loadAgent` — the same resolution `Attacher.java` relies on
+ * already existing for `Agent-Class` itself.
+ *
+ * **`Agent.java`/`Attacher.java`/`MANIFEST.MF` live in `packages/orchestrator/jvm-agent/`,
+ * a sibling of `src/` and `dist/`, NOT inside `src/jvm-agent/` alongside
+ * this file.** Found the hard way, while proving RT-201 from a package
+ * OTHER than this one (`@descry/vertical-slice`'s test, importing through
+ * the compiled `@descryy/runtime-orchestrator` package boundary rather than
+ * this repo's own `src/`): `tsc` only ever emits `.js`/`.d.ts` for `.ts`
+ * sources, so a `.java` file nested inside `src/jvm-agent/` had no
+ * counterpart under `dist/jvm-agent/` at all, and this module's own
+ * `import.meta.url`-relative resolution pointed at a directory that only
+ * existed when running from source. This is the exact same problem
+ * `test-runner-collector.ts` already solved for the JUnit/xUnit reporters
+ * (its own comment: *"Computed from `import.meta.url` like the other
+ * reporter paths rather than imported from `reporters/junit/build.mjs`:
+ * that file is outside this package's `rootDir`"*) — a relative URL that
+ * walks OUT of `src/`/`dist/` to a shared sibling resolves identically from
+ * either one, since both sit at the same depth under `packages/orchestrator/`.
+ * Applied here the same way, one level up from that file's `reporters/`.
+ */
+export declare const JVM_AGENT_DIR: string;
+export declare const BYTEBUDDY_JAR: string;
+/** Fetches the pinned ByteBuddy jar if absent or its checksum no longer matches — refuses a mismatch rather than proceeding, since this jar is both compiled against and loaded into a target JVM. */
+export declare function ensureByteBuddyJar(): Promise<string>;
+/** `$JAVA_HOME/lib/tools.jar` if it exists, else derived from `java`'s own reported `java.home`. `null` when neither yields a real file — the JDK 9+, no-`tools.jar` case. */
+export declare function findToolsJarIfPresent(): string | null;
+/** Compiles `Agent.java` and packages it as `agent.jar` with `Agent-Class` in its manifest. Returns the jar's path. */
+export declare function buildJvmAgentJar(): Promise<string>;
+/** Compiles `Attacher.java` to `Attacher.class` in this same directory. Returns the directory to put on the classpath (the class itself, not a jar — one file, no packaging step needed). */
+export declare function buildAttacherClass(): string;
+/** Ensures a directory exists (for the caller's tmp output file), mirroring the small helper every attach module in this package already needs once for its own scratch state. */
+export declare function ensureDir(path: string): void;
+//# sourceMappingURL=build.d.ts.map

package/dist/jvm-agent/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/jvm-agent/build.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAQH,eAAO,MAAM,aAAa,QAA6D,CAAC;AAMxF,eAAO,MAAM,aAAa,QAA6D,CAAC;AAMxF,sMAAsM;AACtM,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC,CAe1D;AAMD,8KAA8K;AAC9K,wBAAgB,qBAAqB,IAAI,MAAM,GAAG,IAAI,CAYrD;AAED,uHAAuH;AACvH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,CA0BxD;AAED,6LAA6L;AAC7L,wBAAgB,kBAAkB,IAAI,MAAM,CAY3C;AAED,kLAAkL;AAClL,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE5C"}

package/dist/jvm-agent/build.js

@@ -0,0 +1,156 @@
+/**
+ * Compiles `Agent.java` into `agent.jar` and `Attacher.java` into
+ * `Attacher.class`, once, and only when the source is newer than the build
+ * output — the same mtime-cache rule `kotlin-server/build.ts` (test fixture
+ * side) already uses, applied here to shipped `src/` code instead of a test
+ * fixture, because the agent and its launcher are real product code:
+ * `attach-to-running-jvm-process.ts` runs the compiled artifacts, it does
+ * not compile them itself at call time.
+ *
+ * **`tools.jar` is JDK-8-only.** `com.sun.tools.attach.VirtualMachine`
+ * shipped inside `tools.jar` through JDK 8; from JDK 9 it moved into the
+ * `jdk.attach` module and is resolvable on the classpath with no extra jar.
+ * `findToolsJarIfPresent` looks for it and returns `null` when absent
+ * (JDK 9+, or a JRE with no `tools.jar` at all) — `Attacher.java` is then
+ * compiled and later run with no extra classpath entry, which is correct
+ * for JDK 9+ but has only been exercised against JDK 8 on this machine (the
+ * only JDK installed here); see this module's own decisions-inbox entry for
+ * that disclosed gap.
+ *
+ * **ByteBuddy, vendored the same way `junit-platform-console-standalone` is
+ * for the JUnit reporter** (`packages/test-runner/reporters/junit/build.mjs`):
+ * one pinned version, fetched once from Maven Central, checksum-verified,
+ * cached beside the agent's own sources — never a build tool. `Agent.java`
+ * needs a real bytecode-manipulation library for `DispatcherServlet`
+ * method-entry advice (RT-201); hand-written raw ASM/bytecode patching for
+ * that is not realistic, and Maven/Gradle here would mean resolving a
+ * dependency tree for one library this single file uses. The plain
+ * `net.bytebuddy:byte-buddy` artifact (not `byte-buddy-dep`) is used
+ * specifically because it repackages its own ASM under
+ * `net.bytebuddy.jar.asm.*` (verified directly against this exact jar,
+ * `unzip -l`) — one self-contained jar, no second dependency to vendor.
+ * `Class-Path: byte-buddy-<version>.jar` in `MANIFEST.MF` is a **static,
+ * version-pinned line** rather than a generated one, so a version bump is a
+ * two-line, reviewable diff (URL/digest here, `Class-Path` in the manifest)
+ * exactly like `junit-platform-console-standalone`'s. It sits beside
+ * `agent.jar` in the same directory as `Agent.java` itself (below) because
+ * the JDK resolves an agent JAR's `Class-Path` manifest entries relative to
+ * the agent JAR's own location, for both `-javaagent` and
+ * `VirtualMachine.loadAgent` — the same resolution `Attacher.java` relies on
+ * already existing for `Agent-Class` itself.
+ *
+ * **`Agent.java`/`Attacher.java`/`MANIFEST.MF` live in `packages/orchestrator/jvm-agent/`,
+ * a sibling of `src/` and `dist/`, NOT inside `src/jvm-agent/` alongside
+ * this file.** Found the hard way, while proving RT-201 from a package
+ * OTHER than this one (`@descry/vertical-slice`'s test, importing through
+ * the compiled `@descryy/runtime-orchestrator` package boundary rather than
+ * this repo's own `src/`): `tsc` only ever emits `.js`/`.d.ts` for `.ts`
+ * sources, so a `.java` file nested inside `src/jvm-agent/` had no
+ * counterpart under `dist/jvm-agent/` at all, and this module's own
+ * `import.meta.url`-relative resolution pointed at a directory that only
+ * existed when running from source. This is the exact same problem
+ * `test-runner-collector.ts` already solved for the JUnit/xUnit reporters
+ * (its own comment: *"Computed from `import.meta.url` like the other
+ * reporter paths rather than imported from `reporters/junit/build.mjs`:
+ * that file is outside this package's `rootDir`"*) — a relative URL that
+ * walks OUT of `src/`/`dist/` to a shared sibling resolves identically from
+ * either one, since both sit at the same depth under `packages/orchestrator/`.
+ * Applied here the same way, one level up from that file's `reporters/`.
+ */
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+export const JVM_AGENT_DIR = fileURLToPath(new URL("../../jvm-agent", import.meta.url));
+/** Pinned. A version bump changes the URL, the digest, and `MANIFEST.MF`'s `Class-Path` line, in one reviewable diff. */
+const BYTEBUDDY_VERSION = "1.15.11";
+const BYTEBUDDY_SHA256 = "fa08998aae1e7bdae83bde0712c50e8444d71c0e0c196bb2247ade8d4ad0eb90";
+const BYTEBUDDY_URL = `https://repo1.maven.org/maven2/net/bytebuddy/byte-buddy/${BYTEBUDDY_VERSION}/byte-buddy-${BYTEBUDDY_VERSION}.jar`;
+export const BYTEBUDDY_JAR = join(JVM_AGENT_DIR, `byte-buddy-${BYTEBUDDY_VERSION}.jar`);
+function digestOf(path) {
+    return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+/** Fetches the pinned ByteBuddy jar if absent or its checksum no longer matches — refuses a mismatch rather than proceeding, since this jar is both compiled against and loaded into a target JVM. */
+export async function ensureByteBuddyJar() {
+    if (existsSync(BYTEBUDDY_JAR) && digestOf(BYTEBUDDY_JAR) === BYTEBUDDY_SHA256)
+        return BYTEBUDDY_JAR;
+    mkdirSync(JVM_AGENT_DIR, { recursive: true });
+    const response = await fetch(BYTEBUDDY_URL);
+    if (!response.ok) {
+        throw new Error(`jvm-agent build: could not fetch ${BYTEBUDDY_URL} — HTTP ${String(response.status)}`);
+    }
+    writeFileSync(BYTEBUDDY_JAR, Buffer.from(await response.arrayBuffer()));
+    const actual = digestOf(BYTEBUDDY_JAR);
+    if (actual !== BYTEBUDDY_SHA256) {
+        throw new Error(`jvm-agent build: checksum mismatch for ${BYTEBUDDY_JAR}\n  expected ${BYTEBUDDY_SHA256}\n  actual   ${actual}`);
+    }
+    return BYTEBUDDY_JAR;
+}
+function newerThan(output, source) {
+    return existsSync(output) && statSync(output).mtimeMs >= statSync(source).mtimeMs;
+}
+/** `$JAVA_HOME/lib/tools.jar` if it exists, else derived from `java`'s own reported `java.home`. `null` when neither yields a real file — the JDK 9+, no-`tools.jar` case. */
+export function findToolsJarIfPresent() {
+    const fromEnv = process.env["JAVA_HOME"];
+    if (fromEnv !== undefined) {
+        const candidate = join(fromEnv, "lib", "tools.jar");
+        if (existsSync(candidate))
+            return candidate;
+    }
+    const probe = spawnSync("java", ["-XshowSettings:properties", "-version"], { encoding: "utf8" });
+    const combined = `${probe.stdout ?? ""}${probe.stderr ?? ""}`;
+    const match = /java\.home\s*=\s*(.+)/.exec(combined);
+    if (match?.[1] === undefined)
+        return null;
+    const candidate = join(match[1].trim(), "lib", "tools.jar");
+    return existsSync(candidate) ? candidate : null;
+}
+/** Compiles `Agent.java` and packages it as `agent.jar` with `Agent-Class` in its manifest. Returns the jar's path. */
+export async function buildJvmAgentJar() {
+    const source = join(JVM_AGENT_DIR, "Agent.java");
+    const jarPath = join(JVM_AGENT_DIR, "agent.jar");
+    const byteBuddyJar = await ensureByteBuddyJar();
+    // Cache invalidates on either input changing -- a ByteBuddy version bump
+    // (new jar path/mtime) must also trigger a rebuild, not just an Agent.java
+    // edit, since the compiled advice classes are compiled against it.
+    if (newerThan(jarPath, source) && newerThan(jarPath, byteBuddyJar))
+        return jarPath;
+    const compiled = spawnSync("javac", ["-cp", byteBuddyJar, "-d", JVM_AGENT_DIR, source], { encoding: "utf8", timeout: 60_000 });
+    if (compiled.status !== 0) {
+        throw new Error(`javac failed to compile Agent.java. This is a toolchain failure, not a test failure:\n${compiled.stdout ?? ""}${compiled.stderr ?? ""}`);
+    }
+    // `Agent.java` now declares nested static classes (the ByteBuddy advice)
+    // -- `javac` emits one `Agent$Name.class` per nested class alongside
+    // `Agent.class`, and every one of them must be in the jar or the JVM
+    // throws NoClassDefFoundError the first time DispatcherServlet is loaded
+    // in the target and the advice class is needed.
+    const agentClassFiles = readdirSync(JVM_AGENT_DIR).filter((name) => name === "Agent.class" || name.startsWith("Agent$"));
+    const jarArgs = ["cfm", jarPath, join(JVM_AGENT_DIR, "MANIFEST.MF")];
+    for (const classFile of agentClassFiles)
+        jarArgs.push("-C", JVM_AGENT_DIR, classFile);
+    const jarred = spawnSync("jar", jarArgs, { encoding: "utf8", timeout: 30_000 });
+    if (jarred.status !== 0) {
+        throw new Error(`jar failed to package agent.jar:\n${jarred.stdout ?? ""}${jarred.stderr ?? ""}`);
+    }
+    return jarPath;
+}
+/** Compiles `Attacher.java` to `Attacher.class` in this same directory. Returns the directory to put on the classpath (the class itself, not a jar — one file, no packaging step needed). */
+export function buildAttacherClass() {
+    const source = join(JVM_AGENT_DIR, "Attacher.java");
+    const classFile = join(JVM_AGENT_DIR, "Attacher.class");
+    if (newerThan(classFile, source))
+        return JVM_AGENT_DIR;
+    const toolsJar = findToolsJarIfPresent();
+    const args = toolsJar !== null ? ["-cp", toolsJar, "-d", JVM_AGENT_DIR, source] : ["-d", JVM_AGENT_DIR, source];
+    const compiled = spawnSync("javac", args, { encoding: "utf8", timeout: 60_000 });
+    if (compiled.status !== 0) {
+        throw new Error(`javac failed to compile Attacher.java. This is a toolchain failure, not a test failure:\n${compiled.stdout ?? ""}${compiled.stderr ?? ""}`);
+    }
+    return JVM_AGENT_DIR;
+}
+/** Ensures a directory exists (for the caller's tmp output file), mirroring the small helper every attach module in this package already needs once for its own scratch state. */
+export function ensureDir(path) {
+    mkdirSync(path, { recursive: true });
+}
+//# sourceMappingURL=build.js.map

package/dist/jvm-agent/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../../src/jvm-agent/build.ts"],"names":[],"mappings":"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"}