@descryy/runtime-orchestrator 0.3.0 → 0.4.1

package/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) Descry
+
+All rights reserved. This software is proprietary and confidential.
+No license, express or implied, to reproduce, distribute, modify, or
+create derivative works is granted except as explicitly agreed in
+writing.

package/dist/attach-to-running-jvm-process.d.ts

@@ -1,71 +1,38 @@
 /**
- * Retroactive attach to an already-running **JVM (Java/Kotlin/…)** process —
- * the JVM item on `RT-attach-to-running-process-scope.md`'s own
- * "deliberately not built" list, and `RT-attach-to-running-jvm-process.md`
- * (decisions-inbox) is the short record of what got measured before any of
- * this was written and why the slice below is the honest first one, not a
- * full CDP-equivalent.
+ * Retroactive attach to an already-running **JVM (Java/Kotlin/…)** process. Not a
+ * full CDP-equivalent; see `RT-attach-to-running-jvm-process.md` (decisions-inbox)
+ * for what was measured before this was written.
  *
- * **The real mechanism, measured against a live JVM on this machine, not
- * assumed from docs.** The JVM ships no built-in signal-to-inspector path
- * the way Node's `SIGUSR1` does. What it does ship, since JDK 6, is the
- * HotSpot Dynamic Attach mechanism: a launcher process calls
- * `com.sun.tools.attach.VirtualMachine.attach(pid)`, which creates
- * `.attach_pid<pid>` and signals the target with `SIGQUIT`; the target's own
- * attach-listener thread (started lazily on first use, already running in
- * every stock HotSpot JVM — nothing needs to be enabled at the target's own
- * launch) opens a Unix-domain socket at `.java_pid<pid>` in its temp
- * directory and accepts commands over it. `jcmd`/`jstack`/`VisualVM` all use
- * exactly this. Measured directly here: attached to a plain `java
- * QuietServer` process with no `-agentlib`/`-Djdk.attach` flags of any kind
- * and no restart, confirming this is genuinely retroactive, the same
- * standing Node's `SIGUSR1` slice has.
+ * **Mechanism, measured against a live JVM, not assumed from docs.** The JVM has
+ * no `SIGUSR1`-equivalent, but ships (since JDK 6) HotSpot Dynamic Attach:
+ * `VirtualMachine.attach(pid)` creates `.attach_pid<pid>`, signals `SIGQUIT`, and
+ * the target's attach-listener thread (already running in every stock HotSpot
+ * JVM, nothing to enable at launch) opens a Unix socket at `.java_pid<pid>` and
+ * accepts commands — the same thing `jcmd`/`jstack`/`VisualVM` use. Measured:
+ * attached to a plain `java QuietServer` with no special flags and no restart,
+ * confirming this is genuinely retroactive.
  *
- * **What this channel can actually give — measured, and narrower than
- * CDP.** `VirtualMachine.loadAgent(jar, args)` loads a real Java agent
- * (`java.lang.instrument.Instrumentation`) into the target's own JVM,
- * running as that JVM's own code — a strictly more powerful primitive than
- * CDP's remote-debugging protocol. This first slice used only the cheapest
- * real capability inside it: `Thread.setDefaultUncaughtExceptionHandler`
- * (`jvm-agent/Agent.java`), which needs no bytecode instrumentation at all,
- * and **did not see an exception a framework already caught** — a request
- * handler's own try/catch, a servlet container's default error page, any
- * `@ExceptionHandler` — because by definition those exceptions never reach
- * "uncaught." `SelfFailingServer.java` (the existing execute-mode fixture)
- * catches and logs its own thrown exception for exactly this reason, so it
- * is not a fixture this module's own test can reuse; see
- * `test/fixtures/jvm-attach/BackgroundThreadThrows.java`, a real thread that
- * throws with nothing catching it, the one shape that first slice could see.
+ * **Narrower than CDP.** `VirtualMachine.loadAgent(jar, args)` loads a real Java
+ * agent (`Instrumentation`) — more powerful than CDP's remote-debugging protocol
+ * in principle, but this slice only uses `Thread.setDefaultUncaughtExceptionHandler`
+ * (`jvm-agent/Agent.java`), so it never sees an exception a framework already
+ * caught (a try/catch, a servlet error page, `@ExceptionHandler`). RT-201 closed
+ * one specific instance of that gap: `Agent.java` also installs a ByteBuddy
+ * `ClassFileTransformer` tapping
+ * `DispatcherServlet#processHandlerException` — Spring MVC's single stable
+ * exception choke point — reported as `"framework-caught-exception"`, parsed
+ * below and emitted with `payload.handled === true`. This closes only that one
+ * choke point: a catch absorbed inside a `@Service` method, or any non-Spring
+ * framework, is still invisible.
  *
- * **RT-201 closed one specific, real instance of that gap**, using the same
- * `Instrumentation` this module already hands the agent: `Agent.java` now
- * also installs a ByteBuddy `ClassFileTransformer` (see that file's own
- * header comment for the full mechanism and what was measured) that taps
- * `org.springframework.web.servlet.DispatcherServlet#processHandlerException`
- * — Spring MVC's single stable choke point for every exception-handling
- * path — and reports what it catches as a `"framework-caught-exception"`
- * event, parsed below as `isFrameworkCaughtExceptionEvent` and emitted as
- * `EXCEPTION` evidence with `payload.handled === true`. **This closes only
- * that one choke point.** A catch that never reaches Spring's dispatcher —
- * absorbed inside a `@Service` method, logged nowhere — is still invisible,
- * and no non-Spring framework is instrumented at all. `Runtime.exceptionThrown`'s
- * CDP-side reach (any throw the debugger is configured to pause on,
- * regardless of framework) still has no equivalent here.
+ * **No console-output capture** — `System.out`/`err` aren't intercepted; that's
+ * `attachToRunningProcess`'s job for a target already logging to a file.
+ * `capabilities()` reports `backendLogAccess` unavailable for that reason.
  *
- * **No console-output capture in this slice.** Unlike CDP's
- * `Runtime.consoleAPICalled`, `System.out`/`System.err` are not intercepted
- * — a target already logging to a file is exactly `attachToRunningProcess`'s
- * (the file-based sibling) job, and duplicating that here would be two
- * mechanisms claiming the same evidence. `capabilities()` reports
- * `backendLogAccess` unavailable for that reason, unlike the Node slice.
- *
- * **Launcher is a real JDK tool process, not a library call.** There is no
- * Node/native binding for the Attach API in this repo and none is added —
- * `jvm-agent/build.ts` compiles `Attacher.java` once (cached by mtime, same
- * rule `kotlin-server/build.ts` already uses) and this module spawns it as a
- * short-lived `java` child process, the same "one helper invocation, not a
- * new protocol client" shape `discoverNodeInspectorUrl`'s `process.kill`
- * call has, just through a JDK tool instead of a POSIX signal.
+ * **Launcher is a real JDK tool process, not a library call** — no Node/native
+ * Attach-API binding exists or is added. `jvm-agent/build.ts` compiles
+ * `Attacher.java` once (mtime-cached) and this module spawns it as a short-lived
+ * `java` child process.
  */
 import type { Collector } from "@descryy/runtime-contracts";
 export interface AttachToRunningJvmProcessOptions {
@@ -78,43 +45,23 @@ export interface AttachToRunningJvmProcessOptions {
     /** How often to check the agent's output file for new events. */
     readonly pollIntervalMs?: number;
     /**
-     * Repo-relative source roots plus the absolute repo root, enabling a JVM
-     * frame's bare basename to be reconstructed into a repo-relative path that
-     * graph correlation can actually join on (RT-202, extending RT-162's fix
-     * from the log-tailing path to this one).
-     *
-     * ## Why the attach path needed this too, and why it went unnoticed
-     *
-     * `JvmRuntimeAdapterOptions.sourceRoots` (`@descryy/runtime-adapter-jvm`)
-     * already fixed this for evidence produced by `createJvmStackTraceParser`
-     * — the JVM prints a bare basename (`ProbeApplication.java`), never a
-     * path, so `resolveSymbolNode` correctly refuses to match on it alone
-     * (RT-031's identity-proxy rule), and reconstruction from the frame's
-     * declaring type is what lets the two sides join. This collector builds
-     * its `StackFrame.location` directly from the Java agent's own captured
-     * `StackTraceElement` fields (`frameToStackFrame` below) and never went
-     * through that parser at all, so it never got the fix — invisible until
-     * RT-202, because this mechanism's only fixture before then
-     * (`BackgroundThreadThrows.java`) is in the default package, where
-     * reconstruction is a no-op regardless (no dot in the declaring type).
+     * Repo-relative source roots plus the absolute repo root, so a JVM frame's bare
+     * basename can be reconstructed into a repo-relative path graph correlation can
+     * join on (RT-202, extending RT-162's fix from the log-tailing path to this one).
      *
-     * ## Reimplemented here, not imported — a deliberate, disclosed duplication
+     * The JVM prints a bare basename (`ProbeApplication.java`), never a path, so
+     * `resolveSymbolNode` refuses to match on it alone (RT-031). This collector builds
+     * `StackFrame.location` straight from the agent's captured `StackTraceElement`
+     * fields, bypassing `createJvmStackTraceParser` entirely, so RT-162's earlier fix
+     * there never reached this path — invisible until RT-202, since this mechanism's
+     * only prior fixture was in the default package, where reconstruction is a no-op.
      *
-     * `packages/orchestrator`'s own `src/` has never taken a real dependency
-     * on any `@descryy/runtime-adapter-*` package — only
-     * `@descryy/runtime-adapter-typescript` is one, for an unrelated
-     * default-path reason, and every other language adapter (including
-     * `@descryy/runtime-adapter-jvm`) is a devDependency used solely by this
-     * package's own tests. Importing the JVM-specific reconstruction function
-     * into this language-agnostic-by-convention module would be a bigger
-     * architectural change than this gap warrants, so
-     * `reconstructJvmSourcePath` below is a second copy of the exact same
-     * algorithm (declaring type + basename + candidate roots + `existsSync`
-     * check, discarded rather than fabricated when nothing is on disk) —
-     * unlike other duplication this project has measured drifting silently,
-     * both copies are tiny, pure, and named after the one behaviour they
-     * implement, so a future change to one is easy to notice is missing from
-     * the other.
+     * `reconstructJvmSourcePath` below is a deliberate second copy of
+     * `jvm-stack-trace-parser.ts`'s algorithm, not a shared import: this package
+     * never takes a real dependency on any `@descryy/runtime-adapter-*` package
+     * (JVM's included), and importing the JVM-specific function here would be a
+     * bigger architectural change than this gap warrants. Both copies are tiny,
+     * pure, and named after the one behaviour they implement.
      */
     readonly sourceRoots?: {
         readonly repoRoot: string;

package/dist/attach-to-running-jvm-process.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attach-to-running-jvm-process.d.ts","sourceRoot":"","sources":["../src/attach-to-running-jvm-process.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AAOH,OAAO,KAAK,EAAE,SAAS,EAAyF,MAAM,4BAA4B,CAAC;AAMnJ,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,+IAA+I;IAC/I,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,iLAAiL;IACjL,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,iEAAiE;IACjE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;KACnC,CAAC;CACH;AAsKD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,gCAAgC,GAAG,SAAS,CAwH9F"}
+{"version":3,"file":"attach-to-running-jvm-process.d.ts","sourceRoot":"","sources":["../src/attach-to-running-jvm-process.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAOH,OAAO,KAAK,EAAE,SAAS,EAAyF,MAAM,4BAA4B,CAAC;AAMnJ,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,+IAA+I;IAC/I,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,iLAAiL;IACjL,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,iEAAiE;IACjE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;KACnC,CAAC;CACH;AAoLD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,gCAAgC,GAAG,SAAS,CA0N9F"}