@descryy/runtime-orchestrator 0.3.0 → 0.4.0

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

@@ -1,42 +1,21 @@
 /**
- * Attach observation to a process Descry did not spawn (RUNTIME-CHECKLIST.md
- * §39 item 1's open half — "execute yes; attach: not implemented").
+ * Attach observation to a process Descry did not spawn.
  *
- * **What this honestly covers, and what it does not.** Every collector in
- * this repo reads a `ProcessOutputSource` (`process-output.ts`), and the
- * only live implementation (`createPollingProcessOutputSource`) is already
- * source-agnostic — it needs a growing `readOutput(): string` and a boolean
- * `isFinished()`, nothing that presumes we spawned the process. `execute`
- * satisfies those from `ManagedProcess`'s in-memory pipe buffer
- * (`process-manager.ts`), which exists only because `child_process.spawn`
- * wired the pipes *at spawn time* — Node (and POSIX generally) gives no way
- * to retroactively attach to another process's stdout/stderr fds after the
- * fact. So true retroactive attach to an *arbitrary* already-running
- * process — one that logs to a TTY, or that never wrote its output
- * anywhere Descry can now reach — is not implemented here and is not a
- * bounded slice: it would need a per-language debugger/inspector protocol
- * (e.g. Node's own `SIGUSR1` inspector activation, JVM's Attach API, a
- * `/proc` ptrace shim on Linux only), each its own multi-week surface,
- * scoped in `documents/decisions-inbox/RT-attach-to-running-process-scope.md`.
+ * Node/POSIX give no way to retroactively attach to another process's
+ * stdout/stderr fds after the fact — pipes are only wired at spawn time. So true
+ * generic attach (a process that logs to a TTY, or never wrote output anywhere
+ * reachable) is not implemented; it would need a per-language debugger/inspector
+ * protocol, scoped separately in `documents/decisions-inbox/RT-attach-to-running-process-scope.md`.
  *
- * What IS real and implemented: attaching to a process that is already
- * running and was already directed to write its output to a file Descry
- * can read — e.g. a dev server the user started with
- * `npm run dev > server.log 2>&1 &`, or any long-lived service whose
- * stdout/stderr is already redirected to disk. This is candidate (a), not
- * (b): narrower than generic attach, but a real, testable capability —
- * `attachToRunningProcess` verifies the target PID is alive, then reuses
- * the exact same live-tail machinery `execute` uses, catching up on
- * whatever the file already held *before* attach and then tailing new
- * writes exactly like a spawned process's buffer.
+ * What IS implemented: attaching to a process already directed to write output to
+ * a file Descry can read (e.g. `npm run dev > server.log 2>&1 &`).
+ * `attachToRunningProcess` verifies the target pid is alive, then reuses `execute`'s
+ * live-tail machinery, catching up on what the file already held and tailing new
+ * writes the same way.
  *
- * **Shares `execute`'s known identity gap (RT-024).** `isProcessAlive`
- * confirms *a* process with this pid exists, not that it is the one the
- * caller thinks it is — pids are reused by the OS. `execute`'s own
- * readiness checks carry the identical caveat (see `readiness.ts`'s own
- * doc comment) and it is disclosed there rather than solved; the same is
- * true here, for the same reason: nothing in a bare pid or a bare file
- * path proves provenance.
+ * **Shares `execute`'s identity gap (RT-024).** `isProcessAlive` confirms a process
+ * with this pid exists, not that it's the one the caller thinks — pids are reused.
+ * Disclosed, not solved, same as `readiness.ts`.
  */
 import type { ProcessOutputSource } from "@descryy/runtime-backend-observation";
 export interface AttachToRunningProcessOptions {
@@ -46,31 +25,18 @@ export interface AttachToRunningProcessOptions {
     /** Path to a file the target process is already writing its stdout/stderr to. Read in full on every poll — same growing-buffer contract `ManagedProcess.readOutput()` has, not a delta. */
     readonly logFilePath: string;
     /**
-     * The declared service this pid is, carried onto every `Evidence` a collector
-     * built over this source emits. Optional here, unlike on the source itself,
-     * because an attach to a bare pid genuinely may have no declared service
-     * behind it — and omitting it resolves to `null`, which is a statement, not a
-     * gap. Supply it whenever the caller *does* know: without it, correlation
-     * cannot look a scope up for anything this source produces.
+     * The declared service this pid is. Optional because a bare-pid attach may
+     * genuinely have none declared — omitting it resolves to `null`, a statement,
+     * not a gap. Without it, correlation can't look up a scope for this source.
      */
     readonly serviceName?: string | null;
     /**
-     * True once the caller's observation window has closed. Required, and the
-     * reason it is not optional is the bug it was added to fix.
-     *
-     * A source over an attached target has two independent reasons to end: the
-     * target exited, or the caller stopped watching. The liveness check covers
-     * only the first, and for a healthy attached service it is never true — so
-     * with no second signal the source polls a live buffer forever. Two things
-     * follow, and the second is the worse: the final line held in the splitter
-     * for want of a newline is never flushed, and a consumer that stops
-     * iterating never gets its generator back.
-     *
-     * The spawn path has always had this signal (`instrumented-execution.ts`
-     * flips a `finished` flag immediately before `collector.stop()`, with an
-     * ordering comment explaining that stop() would otherwise wait forever).
-     * This is the same signal, and defaulting it to "never stops" would leave
-     * both failures reachable by simply not passing it.
+     * True once the caller's observation window has closed. Required: a source has
+     * two independent end conditions (target exited, or caller stopped watching),
+     * and the liveness check alone never fires for a healthy target — without this,
+     * the source polls forever, the final unflushed line is lost, and a consumer
+     * that stops iterating never gets its generator back. Same signal
+     * `instrumented-execution.ts` uses before `collector.stop()`.
      */
     readonly stopObserving: () => boolean;
     readonly pollIntervalMs?: number;
@@ -83,21 +49,17 @@ export interface AttachToRunningProcessOptions {
  */
 export declare function isProcessAlive(pid: number): boolean;
 /**
- * Attach to an already-running process via a log file it is already
- * writing to. Throws immediately if the pid is not alive at call time —
- * refusing rather than returning a source that would silently never emit
- * anything, the same "loud, not quiet" contract `ProcessCollector` uses for
- * its own ordering requirement.
+ * Attach to an already-running process via a log file it is already writing to.
+ * Throws immediately if the pid isn't alive — refuses rather than returning a
+ * source that would silently never emit anything.
  *
- * Lines already in `logFilePath` at attach time are yielded first (the
- * "already running before we attached" evidence this is for), followed by
- * whatever the target writes afterward — indistinguishable, once attached,
- * from `execute`'s own live tail.
+ * Lines already in `logFilePath` at attach time are yielded first, followed by
+ * whatever the target writes afterward — indistinguishable from `execute`'s live
+ * tail once attached.
  *
- * **Ending.** The source ends when the caller's window closes or the target
- * exits, whichever comes first — see `stopObserving`. Both halves are needed:
- * the liveness check alone never fires for a healthy target, and the window
- * signal alone would poll a dead one until the caller noticed.
+ * Ends when the caller's window closes or the target exits, whichever comes
+ * first (see `stopObserving`) — both are needed, or a healthy target polls
+ * forever, or a dead one polls until the caller notices.
  */
 export declare function attachToRunningProcess(options: AttachToRunningProcessOptions): ProcessOutputSource;
 //# sourceMappingURL=attach-to-running-process.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"attach-to-running-process.d.ts","sourceRoot":"","sources":["../src/attach-to-running-process.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAIhF,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2HAA2H;IAC3H,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,2LAA2L;IAC3L,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,OAAO,CAAC;IACtC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOnD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,6BAA6B,GAAG,mBAAmB,CA8BlG"}
+{"version":3,"file":"attach-to-running-process.d.ts","sourceRoot":"","sources":["../src/attach-to-running-process.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAIhF,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2HAA2H;IAC3H,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,2LAA2L;IAC3L,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,OAAO,CAAC;IACtC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOnD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,6BAA6B,GAAG,mBAAmB,CA2BlG"}

package/dist/attach-to-running-process.js

@@ -1,42 +1,21 @@
 /**
- * Attach observation to a process Descry did not spawn (RUNTIME-CHECKLIST.md
- * §39 item 1's open half — "execute yes; attach: not implemented").
+ * Attach observation to a process Descry did not spawn.
  *
- * **What this honestly covers, and what it does not.** Every collector in
- * this repo reads a `ProcessOutputSource` (`process-output.ts`), and the
- * only live implementation (`createPollingProcessOutputSource`) is already
- * source-agnostic — it needs a growing `readOutput(): string` and a boolean
- * `isFinished()`, nothing that presumes we spawned the process. `execute`
- * satisfies those from `ManagedProcess`'s in-memory pipe buffer
- * (`process-manager.ts`), which exists only because `child_process.spawn`
- * wired the pipes *at spawn time* — Node (and POSIX generally) gives no way
- * to retroactively attach to another process's stdout/stderr fds after the
- * fact. So true retroactive attach to an *arbitrary* already-running
- * process — one that logs to a TTY, or that never wrote its output
- * anywhere Descry can now reach — is not implemented here and is not a
- * bounded slice: it would need a per-language debugger/inspector protocol
- * (e.g. Node's own `SIGUSR1` inspector activation, JVM's Attach API, a
- * `/proc` ptrace shim on Linux only), each its own multi-week surface,
- * scoped in `documents/decisions-inbox/RT-attach-to-running-process-scope.md`.
+ * Node/POSIX give no way to retroactively attach to another process's
+ * stdout/stderr fds after the fact — pipes are only wired at spawn time. So true
+ * generic attach (a process that logs to a TTY, or never wrote output anywhere
+ * reachable) is not implemented; it would need a per-language debugger/inspector
+ * protocol, scoped separately in `documents/decisions-inbox/RT-attach-to-running-process-scope.md`.
  *
- * What IS real and implemented: attaching to a process that is already
- * running and was already directed to write its output to a file Descry
- * can read — e.g. a dev server the user started with
- * `npm run dev > server.log 2>&1 &`, or any long-lived service whose
- * stdout/stderr is already redirected to disk. This is candidate (a), not
- * (b): narrower than generic attach, but a real, testable capability —
- * `attachToRunningProcess` verifies the target PID is alive, then reuses
- * the exact same live-tail machinery `execute` uses, catching up on
- * whatever the file already held *before* attach and then tailing new
- * writes exactly like a spawned process's buffer.
+ * What IS implemented: attaching to a process already directed to write output to
+ * a file Descry can read (e.g. `npm run dev > server.log 2>&1 &`).
+ * `attachToRunningProcess` verifies the target pid is alive, then reuses `execute`'s
+ * live-tail machinery, catching up on what the file already held and tailing new
+ * writes the same way.
  *
- * **Shares `execute`'s known identity gap (RT-024).** `isProcessAlive`
- * confirms *a* process with this pid exists, not that it is the one the
- * caller thinks it is — pids are reused by the OS. `execute`'s own
- * readiness checks carry the identical caveat (see `readiness.ts`'s own
- * doc comment) and it is disclosed there rather than solved; the same is
- * true here, for the same reason: nothing in a bare pid or a bare file
- * path proves provenance.
+ * **Shares `execute`'s identity gap (RT-024).** `isProcessAlive` confirms a process
+ * with this pid exists, not that it's the one the caller thinks — pids are reused.
+ * Disclosed, not solved, same as `readiness.ts`.
  */
 import { readFileSync } from "node:fs";
 import { createPollingProcessOutputSource } from "./polling-output-source.js";
@@ -56,21 +35,17 @@ export function isProcessAlive(pid) {
     }
 }
 /**
- * Attach to an already-running process via a log file it is already
- * writing to. Throws immediately if the pid is not alive at call time —
- * refusing rather than returning a source that would silently never emit
- * anything, the same "loud, not quiet" contract `ProcessCollector` uses for
- * its own ordering requirement.
+ * Attach to an already-running process via a log file it is already writing to.
+ * Throws immediately if the pid isn't alive — refuses rather than returning a
+ * source that would silently never emit anything.
  *
- * Lines already in `logFilePath` at attach time are yielded first (the
- * "already running before we attached" evidence this is for), followed by
- * whatever the target writes afterward — indistinguishable, once attached,
- * from `execute`'s own live tail.
+ * Lines already in `logFilePath` at attach time are yielded first, followed by
+ * whatever the target writes afterward — indistinguishable from `execute`'s live
+ * tail once attached.
  *
- * **Ending.** The source ends when the caller's window closes or the target
- * exits, whichever comes first — see `stopObserving`. Both halves are needed:
- * the liveness check alone never fires for a healthy target, and the window
- * signal alone would poll a dead one until the caller noticed.
+ * Ends when the caller's window closes or the target exits, whichever comes
+ * first (see `stopObserving`) — both are needed, or a healthy target polls
+ * forever, or a dead one polls until the caller notices.
  */
 export function attachToRunningProcess(options) {
     if (!isProcessAlive(options.pid)) {
@@ -79,9 +54,7 @@ export function attachToRunningProcess(options) {
     }
     return createPollingProcessOutputSource({
         processId: options.processId,
-        // An attach may or may not have a declared service behind it. `null` here
-        // is the honest answer for an ad-hoc attach to a pid, and it is stated
-        // rather than defaulted in the source itself.
+        // an ad-hoc attach may have no declared service; null is the honest answer
         serviceName: options.serviceName ?? null,
         readOutput: () => {
             try {
@@ -92,9 +65,8 @@ export function attachToRunningProcess(options) {
                 throw new Error(`attachToRunningProcess: could not read log file "${options.logFilePath}" for pid ${options.pid}: ${detail}`);
             }
         },
-        // A disjunction, not a replacement: either reason genuinely ends the
-        // source, and dropping the liveness half would leave a target that dies
-        // mid-window polled until the caller happened to notice.
+        // either reason ends the source; dropping the liveness half would leave a
+        // target that dies mid-window polled until the caller noticed
         isFinished: () => options.stopObserving() || !isProcessAlive(options.pid),
         ...(options.pollIntervalMs !== undefined ? { pollIntervalMs: options.pollIntervalMs } : {}),
     });

package/dist/attach-to-running-process.js.map

@@ -1 +1 @@
-{"version":3,"file":"attach-to-running-process.js","sourceRoot":"","sources":["../src/attach-to-running-process.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAIvC,OAAO,EAAE,gCAAgC,EAAE,MAAM,4BAA4B,CAAC;AAuC9E;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAQ,KAA+B,CAAC,IAAI,KAAK,OAAO,CAAC;IAC3D,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAsC;IAC3E,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,+BAA+B,OAAO,CAAC,GAAG,SAAS,OAAO,CAAC,SAAS,qCAAqC;YACvG,6FAA6F,CAChG,CAAC;IACJ,CAAC;IAED,OAAO,gCAAgC,CAAC;QACtC,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,0EAA0E;QAC1E,uEAAuE;QACvE,8CAA8C;QAC9C,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI;QACxC,UAAU,EAAE,GAAG,EAAE;YACf,IAAI,CAAC;gBACH,OAAO,YAAY,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;YACnD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACtE,MAAM,IAAI,KAAK,CACb,oDAAoD,OAAO,CAAC,WAAW,aAAa,OAAO,CAAC,GAAG,KAAK,MAAM,EAAE,CAC7G,CAAC;YACJ,CAAC;QACH,CAAC;QACD,qEAAqE;QACrE,wEAAwE;QACxE,yDAAyD;QACzD,UAAU,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC;QACzE,GAAG,CAAC,OAAO,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5F,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"attach-to-running-process.js","sourceRoot":"","sources":["../src/attach-to-running-process.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAIvC,OAAO,EAAE,gCAAgC,EAAE,MAAM,4BAA4B,CAAC;AA0B9E;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAQ,KAA+B,CAAC,IAAI,KAAK,OAAO,CAAC;IAC3D,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAsC;IAC3E,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,+BAA+B,OAAO,CAAC,GAAG,SAAS,OAAO,CAAC,SAAS,qCAAqC;YACvG,6FAA6F,CAChG,CAAC;IACJ,CAAC;IAED,OAAO,gCAAgC,CAAC;QACtC,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,2EAA2E;QAC3E,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI;QACxC,UAAU,EAAE,GAAG,EAAE;YACf,IAAI,CAAC;gBACH,OAAO,YAAY,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;YACnD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACtE,MAAM,IAAI,KAAK,CACb,oDAAoD,OAAO,CAAC,WAAW,aAAa,OAAO,CAAC,GAAG,KAAK,MAAM,EAAE,CAC7G,CAAC;YACJ,CAAC;QACH,CAAC;QACD,0EAA0E;QAC1E,8DAA8D;QAC9D,UAAU,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC;QACzE,GAAG,CAAC,OAAO,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5F,CAAC,CAAC;AACL,CAAC"}

package/dist/cdp-client.d.ts

@@ -1,25 +1,15 @@
 /**
  * A minimal Chrome DevTools Protocol client over a raw `ws://` URL.
  *
- * **Why this exists rather than reusing something already in the repo.**
- * `packages/browser` speaks CDP too, but only through Playwright's own
- * `page.on("console"/"pageerror")` API (`browser-console-collector.ts`) —
- * Playwright owns the actual WebSocket and the Target/Page domain framing
- * underneath it, and never exposes a bare "connect to an arbitrary `ws://`
- * endpoint and read raw CDP frames" surface. A Node inspector session has no
- * `Target`/`Page` domains at all — it is a single top-level session speaking
- * `Runtime`/`Debugger`/`Console` directly — so Playwright's browser
- * abstraction does not fit it even if pressed into service. Checked before
- * writing this: nothing else in the repo opens a WebSocket to a CDP
- * endpoint directly. This is that client, kept protocol-family-generic (it
- * knows nothing about "Node" or "browser") so a future CDP target of either
- * kind can reuse it instead of a third one being written.
+ * `packages/browser` speaks CDP only through Playwright's console API, which owns its
+ * own WebSocket and Target/Page framing and has no "connect to an arbitrary ws:// and
+ * read raw CDP frames" surface — a Node inspector session has no Target/Page domains
+ * at all, so that abstraction doesn't fit. Kept protocol-family-generic (no "Node" or
+ * "browser" knowledge) so either kind of CDP target can reuse it.
  *
- * CDP-over-WebSocket is JSON-RPC-shaped: a sent message carries `id` and
- * gets exactly one `{id, result}` or `{id, error}` reply; an event has
- * `method`/`params` and no `id`. This client does nothing more than that
- * framing — domain-specific method names and event shapes belong to the
- * caller, not here.
+ * CDP-over-WebSocket is JSON-RPC-shaped: a sent message carries `id` and gets exactly
+ * one `{id, result}` or `{id, error}` reply; an event has `method`/`params`, no `id`.
+ * This client does only that framing — method names and event shapes are the caller's.
  */
 export interface CdpSession {
     /** Sends a CDP command and resolves with its `result` once the matching `id` reply arrives. Rejects on a CDP-reported `error` or if the socket closes first. */

package/dist/cdp-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cdp-client.d.ts","sourceRoot":"","sources":["../src/cdp-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,UAAU;IACzB,gKAAgK;IAChK,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAChF,qHAAqH;IACrH,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACnF,yFAAyF;IACzF,KAAK,IAAI,IAAI,CAAC;CACf;AAOD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAmFpE"}
+{"version":3,"file":"cdp-client.d.ts","sourceRoot":"","sources":["../src/cdp-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,UAAU;IACzB,gKAAgK;IAChK,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAChF,qHAAqH;IACrH,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACnF,yFAAyF;IACzF,KAAK,IAAI,IAAI,CAAC;CACf;AAOD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAgFpE"}

package/dist/cdp-client.js

@@ -1,25 +1,15 @@
 /**
  * A minimal Chrome DevTools Protocol client over a raw `ws://` URL.
  *
- * **Why this exists rather than reusing something already in the repo.**
- * `packages/browser` speaks CDP too, but only through Playwright's own
- * `page.on("console"/"pageerror")` API (`browser-console-collector.ts`) —
- * Playwright owns the actual WebSocket and the Target/Page domain framing
- * underneath it, and never exposes a bare "connect to an arbitrary `ws://`
- * endpoint and read raw CDP frames" surface. A Node inspector session has no
- * `Target`/`Page` domains at all — it is a single top-level session speaking
- * `Runtime`/`Debugger`/`Console` directly — so Playwright's browser
- * abstraction does not fit it even if pressed into service. Checked before
- * writing this: nothing else in the repo opens a WebSocket to a CDP
- * endpoint directly. This is that client, kept protocol-family-generic (it
- * knows nothing about "Node" or "browser") so a future CDP target of either
- * kind can reuse it instead of a third one being written.
+ * `packages/browser` speaks CDP only through Playwright's console API, which owns its
+ * own WebSocket and Target/Page framing and has no "connect to an arbitrary ws:// and
+ * read raw CDP frames" surface — a Node inspector session has no Target/Page domains
+ * at all, so that abstraction doesn't fit. Kept protocol-family-generic (no "Node" or
+ * "browser" knowledge) so either kind of CDP target can reuse it.
  *
- * CDP-over-WebSocket is JSON-RPC-shaped: a sent message carries `id` and
- * gets exactly one `{id, result}` or `{id, error}` reply; an event has
- * `method`/`params` and no `id`. This client does nothing more than that
- * framing — domain-specific method names and event shapes belong to the
- * caller, not here.
+ * CDP-over-WebSocket is JSON-RPC-shaped: a sent message carries `id` and gets exactly
+ * one `{id, result}` or `{id, error}` reply; an event has `method`/`params`, no `id`.
+ * This client does only that framing — method names and event shapes are the caller's.
  */
 /**
  * Resolves once the socket is open, or rejects if it errors/closes first —
@@ -68,10 +58,7 @@ export function connectCdp(webSocketUrl) {
                 msg = JSON.parse(raw);
             }
             catch {
-                // A frame that is not valid JSON is not a valid CDP message from
-                // any target this protocol defines -- dropped rather than thrown,
-                // the same "unparseable stdout is ignorable noise" rule
-                // `test-runner`'s envelope gate applies to its own stream.
+                // non-JSON frame: not a valid CDP message, dropped rather than thrown
                 return;
             }
             if (msg.id !== undefined) {

package/dist/cdp-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"cdp-client.js","sourceRoot":"","sources":["../src/cdp-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAgBH;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,YAAoB;IAC7C,OAAO,IAAI,OAAO,CAAC,CAAC,cAAc,EAAE,aAAa,EAAE,EAAE;QACnD,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,YAAY,CAAC,CAAC;QAC3C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAwB,CAAC;QAChD,MAAM,SAAS,GAAG,IAAI,GAAG,EAA0D,CAAC;QACpF,IAAI,MAAM,GAAG,CAAC,CAAC;QACf,IAAI,OAAO,GAAG,KAAK,CAAC;QAEpB,SAAS,cAAc,CAAC,KAAY;YAClC,KAAK,MAAM,EAAE,MAAM,EAAE,IAAI,OAAO,CAAC,MAAM,EAAE;gBAAE,MAAM,CAAC,KAAK,CAAC,CAAC;YACzD,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,CAAC;QAED,MAAM,CAAC,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE;YACnC,OAAO,GAAG,IAAI,CAAC;YACf,cAAc,CAAC;gBACb,IAAI,CAAI,MAAc,EAAE,SAAkC,EAAE;oBAC1D,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;oBACpB,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;wBACxC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,OAAmC,EAAE,MAAM,EAAE,CAAC,CAAC;wBAC1E,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;oBACtD,CAAC,CAAC,CAAC;gBACL,CAAC;gBACD,EAAE,CAAC,MAAc,EAAE,OAAkD;oBACnE,IAAI,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;oBAChC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;wBACtB,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;wBAChB,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;oBAC7B,CAAC;oBACD,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;oBACjB,OAAO,GAAG,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;gBACnC,CAAC;gBACD,KAAK;oBACH,MAAM,CAAC,KAAK,EAAE,CAAC;gBACjB,CAAC;aACF,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,CAAC,KAAmB,EAAE,EAAE;YACzD,MAAM,GAAG,GAAG,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC7E,IAAI,GAAsH,CAAC;YAC3H,IAAI,CAAC;gBACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAe,CAAC;YACtC,CAAC;YAAC,MAAM,CAAC;gBACP,iEAAiE;gBACjE,kEAAkE;gBAClE,wDAAwD;gBACxD,2DAA2D;gBAC3D,OAAO;YACT,CAAC;YAED,IAAI,GAAG,CAAC,EAAE,KAAK,SAAS,EAAE,CAAC;gBACzB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBACpC,IAAI,OAAO,KAAK,SAAS;oBAAE,OAAO;gBAClC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBACvB,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;oBAC5B,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,yBAAyB,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;gBAC7F,CAAC;qBAAM,CAAC;oBACN,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBAC9B,CAAC;gBACD,OAAO;YACT,CAAC;YAED,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAC7B,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBACtC,IAAI,GAAG,KAAK,SAAS;oBAAE,OAAO;gBAC9B,KAAK,MAAM,OAAO,IAAI,GAAG;oBAAE,OAAO,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;YACvD,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE;YACpC,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,qCAAqC,YAAY,EAAE,CAAC,CAAC;YAC7E,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,OAAO,GAAG,IAAI,CAAC;gBACf,aAAa,CAAC,KAAK,CAAC,CAAC;YACvB,CAAC;YACD,cAAc,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE;YACpC,cAAc,CAAC,IAAI,KAAK,CAAC,oBAAoB,YAAY,SAAS,CAAC,CAAC,CAAC;QACvE,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"cdp-client.js","sourceRoot":"","sources":["../src/cdp-client.ts"],"names":[],"mappings":"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"}

package/dist/cgroup-partial-restriction.d.ts

@@ -1,123 +1,76 @@
 /**
- * Partial going-forward resource restriction for an already-running,
- * attached-to process, via cgroups v2 -- the second, narrower alternative
- * next to respawn-and-supervise (`respawn-and-supervise.ts`).
+ * Partial going-forward resource restriction for an already-running, attached-to
+ * process, via cgroups v2 — narrower alternative to `respawn-and-supervise.ts`.
  *
- * **What this genuinely gets you, stated exactly, because the honest
- * boundary here is not the same shape as spawn-mode's.** Moving a live
- * pid's cgroup membership (writing it into a delegated cgroup's own
- * `cgroup.procs`, per the kernel's cgroups v2 unified hierarchy) applies
- * real, kernel-enforced resource limits -- `memory.max`, `cpu.max`,
- * `pids.max` -- to a process this runtime never spawned, without killing
- * or restarting it. That is real and this module proves it for real (see
- * the test suite). **It does NOT, and structurally cannot, give the moved
- * process any filesystem or network isolation.** Changing which mount or
- * network namespace an already-running process belongs to needs `setns()`
- * against a live pid -- a fundamentally different, far more invasive
- * operation than a cgroup move, not attempted here and out of scope for
- * this pass. Every value this module returns, and every place this
- * capability is described, says so: `CGROUP_PARTIAL_RESTRICTION_SCOPE`
- * below is the literal, load-bearing string every result carries, precisely
- * so nothing downstream can round it up to "sandboxed" or "isolated" --
- * words that would misrepresent this as equivalent to `sandbox.ts`'s real
- * spawn-time bwrap isolation.
+ * Moving a live pid into a delegated cgroup applies real kernel-enforced limits
+ * (`memory.max`, `cpu.max`, `pids.max`) without killing/restarting it. **It does
+ * NOT and cannot give filesystem or network isolation** — that needs `setns()`
+ * against a live pid, out of scope here. `CGROUP_PARTIAL_RESTRICTION_SCOPE` is the
+ * literal string every result carries so nothing downstream rounds this up to
+ * "sandboxed"/"isolated" (which would misrepresent it as `sandbox.ts`'s real
+ * spawn-time bwrap isolation).
  *
- * **How the delegated cgroup is found -- measured on this host, not
- * assumed from cgroups v2 documentation.** A non-root user cannot write
- * anywhere under `/sys/fs/cgroup` by default; what makes any of this
- * possible at all is a systemd user session's own delegation
- * (`user@<uid>.service`, `Delegate=yes`), which typically extends through
- * `app.slice`/`session.slice`/`background.slice` beneath it. But
- * delegation is not uniform all the way down: cgroups v2's "no internal
- * processes" rule means a *leaf* cgroup that already directly holds a
- * process (a systemd `.scope`, including the very one this Node process
- * itself runs in) generally cannot have its `subtree_control` extended
- * further -- writing to it fails with `EBUSY`, measured directly against
- * this repo's own dev host while building this module. `findDelegatedCgroupAncestor`
- * therefore does not trust `cgroup.subtree_control` text or permission
- * bits alone; it walks up from this process's own `/proc/self/cgroup` path
- * and, at each ancestor, creates a real, temporary probe child directory
- * and checks whether the kernel actually gave it a `memory.max` file --
- * the only way to honestly know a given ancestor's delegation reaches that
- * far, empirically, the same "prove it against the real mechanism" standard
- * `sandbox.ts`'s own escape tests hold spawn-mode isolation to.
+ * Finding the delegated ancestor: a non-root user can only write under
+ * `/sys/fs/cgroup` where a systemd user session delegates it (`Delegate=yes`).
+ * Delegation isn't uniform all the way down — a leaf cgroup already holding a
+ * process (e.g. this Node process's own scope) generally can't extend
+ * `subtree_control` further; writing fails `EBUSY` (measured on this repo's dev
+ * host). So `findDelegatedCgroupAncestor` doesn't trust subtree_control text or
+ * permission bits — it walks up from `/proc/self/cgroup` and, at each ancestor,
+ * creates a real temporary probe child and checks whether the kernel actually gave
+ * it a `memory.max` file.
  */
 import type { CapabilityStatus } from "@descryy/runtime-contracts";
-/**
- * The literal, load-bearing scope string. Every `CgroupMoveResult` carries
- * this exact value under `scope` -- never restated by hand elsewhere, so a
- * caller (or a future capability-report string, or a decisions-inbox entry)
- * that quotes `.scope` can never accidentally drift from this wording.
- */
+/** Literal scope string every `CgroupMoveResult` carries under `scope` — never restated by hand, so quotes of it can't drift. */
 export declare const CGROUP_PARTIAL_RESTRICTION_SCOPE: "partial -- resource limits only, no filesystem or network isolation";
 /**
- * Walks up from this process's own cgroup toward `/sys/fs/cgroup`, returning
- * the deepest (most specific) ancestor directory whose children genuinely
- * get a real `memory.max` -- i.e. the actual delegation boundary, not
- * merely a directory this uid happens to own. `null` when cgroups v2 is not
- * mounted, this process's own cgroup path cannot be determined, or no
- * ancestor all the way to the root passes the probe (no delegation at all).
+ * Walks up from this process's cgroup toward `/sys/fs/cgroup`, returning the
+ * deepest ancestor whose children genuinely get a real `memory.max` — the actual
+ * delegation boundary. `null` if cgroups v2 isn't mounted, own path can't be
+ * determined, or no ancestor passes the probe.
  */
 export declare function findDelegatedCgroupAncestor(): string | null;
 export declare function cgroupV2Capability(): CapabilityStatus;
 export interface CgroupResourceLimits {
     /**
-     * Maps to cgroups v2 `memory.max`, in bytes. **Also writes `memory.swap.max=0`
-     * for the same cgroup, deliberately, when this is set** -- measured directly
-     * while building this module: with swap available on the host (the common
-     * case), `memory.max` alone does not kill anything, it just makes the
-     * kernel push the cgroup's pages to swap under pressure, so a caller
-     * declaring a memory cap would silently get "slows down and swaps"
-     * instead of the real, hard boundary the field name promises. Disabling
-     * swap for the created cgroup is what makes `memory.max` an actual
-     * enforced limit (the kernel's own cgroup-aware OOM killer terminates a
-     * process here, SIGKILL, once reclaim genuinely cannot bring usage under
-     * the cap) rather than a soft one. Not independently toggleable in this
-     * pass -- if a future caller genuinely wants "cap it but let it swap,"
-     * that is a real, separate field to add later, not silently assumed here.
+     * Maps to cgroups v2 `memory.max`, in bytes. Also writes `memory.swap.max=0` for
+     * the same cgroup — measured: with swap available, `memory.max` alone doesn't
+     * kill anything, it just pushes pages to swap under pressure. Disabling swap is
+     * what makes it a hard, OOM-killer-enforced limit rather than a soft one. Not
+     * independently toggleable — "cap it but let it swap" would be a separate field.
      */
     readonly memoryMaxBytes?: number;
-    /** Maps to cgroups v2 `pids.max` -- caps the number of tasks (processes/threads) this cgroup may hold at once. */
+    /** Maps to cgroups v2 `pids.max` -- caps tasks (processes/threads) this cgroup may hold. */
     readonly maxProcesses?: number;
     /**
-     * Raw cgroups v2 `cpu.max` value (`"$MAX $PERIOD"`, e.g. `"50000 100000"`
-     * for 50% of one CPU). Declaring this when the delegated ancestor does
-     * not actually expose a writable `cpu.max` to its children is a refusal
-     * (throws), not a silently-dropped limit -- matching `applySandbox`'s own
-     * "declared, refused rather than silently ignored if unenforceable"
-     * precedent. Measured on this repo's own dev host: `cpu` was NOT
-     * delegated at the same level `memory`/`pids` were, so this is a real,
-     * not hypothetical, gap a caller can hit.
+     * Raw cgroups v2 `cpu.max` value (`"$MAX $PERIOD"`, e.g. `"50000 100000"` for
+     * 50% of one CPU). Throws rather than silently dropping if the delegated
+     * ancestor has no writable `cpu.max` — measured on this repo's dev host: `cpu`
+     * was NOT delegated at the same level `memory`/`pids` were.
      */
     readonly cpuMax?: string;
 }
 export interface CgroupMoveResult {
     readonly applied: true;
     readonly cgroupPath: string;
-    /** Always the literal `CGROUP_PARTIAL_RESTRICTION_SCOPE` string -- see its own doc for why this is never restated by hand. */
+    /** Always the literal `CGROUP_PARTIAL_RESTRICTION_SCOPE` string. */
     readonly scope: typeof CGROUP_PARTIAL_RESTRICTION_SCOPE;
     readonly appliedLimits: CgroupResourceLimits;
     /**
      * Best-effort removal of the cgroup this call created. Succeeds only once
-     * `cgroup.procs` is empty -- the pid exited, or was itself moved
-     * elsewhere -- because cgroups v2 refuses to remove a non-empty cgroup,
-     * the same "no internal processes hiding a live one" rule
-     * `findDelegatedCgroupAncestor`'s own probe relies on. Returns whether
-     * removal actually happened; never throws.
+     * `cgroup.procs` is empty (pid exited or moved elsewhere) -- cgroups v2 refuses
+     * to remove a non-empty cgroup. Returns whether removal happened; never throws.
      */
     readonly release: () => boolean;
 }
 /**
- * Moves `options.pid` -- an already-running process this runtime did not
- * spawn -- into a newly created, resource-limited cgroup. Throws (does not
- * silently proceed) when the target is not alive, when `cgroupV2Capability()`
- * reports unavailable, or when a declared limit's controller file does not
- * actually exist under the delegated ancestor found for it.
+ * Moves `options.pid` (a process this runtime did not spawn) into a newly created,
+ * resource-limited cgroup. Throws if the target isn't alive, `cgroupV2Capability()`
+ * is unavailable, or a declared limit's controller file doesn't exist.
  *
- * Limits are written to the new cgroup BEFORE the pid is moved into it, so
- * a process is never observed inside a cgroup with a half-applied limit
- * set; if any write fails, the created (still-empty) cgroup is removed and
- * the error is rethrown rather than left as an orphaned, unlimited group.
+ * Limits are written before the pid is moved in, so a process is never observed
+ * with a half-applied limit set; on any write failure the still-empty cgroup is
+ * removed and the error rethrown, never left orphaned.
  */
 export declare function moveProcessIntoRestrictedCgroup(options: {
     readonly pid: number;

package/dist/cgroup-partial-restriction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cgroup-partial-restriction.d.ts","sourceRoot":"","sources":["../src/cgroup-partial-restriction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAKnE;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,EAAG,qEAA8E,CAAC;AAkD/H;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,GAAG,IAAI,CAiB3D;AAED,wBAAgB,kBAAkB,IAAI,gBAAgB,CAkBrD;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,kHAAkH;IAClH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,8HAA8H;IAC9H,QAAQ,CAAC,KAAK,EAAE,OAAO,gCAAgC,CAAC;IACxD,QAAQ,CAAC,aAAa,EAAE,oBAAoB,CAAC;IAC7C;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC;CACjC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,EAAE;IACvD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B,GAAG,gBAAgB,CA2EnB"}
+{"version":3,"file":"cgroup-partial-restriction.d.ts","sourceRoot":"","sources":["../src/cgroup-partial-restriction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAKnE,iIAAiI;AACjI,eAAO,MAAM,gCAAgC,EAAG,qEAA8E,CAAC;AA2C/H;;;;;GAKG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,GAAG,IAAI,CAc3D;AAED,wBAAgB,kBAAkB,IAAI,gBAAgB,CAkBrD;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,4FAA4F;IAC5F,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,OAAO,gCAAgC,CAAC;IACxD,QAAQ,CAAC,aAAa,EAAE,oBAAoB,CAAC;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC;CACjC;AAED;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,EAAE;IACvD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B,GAAG,gBAAgB,CAsEnB"}