@descryy/runtime-controller 0.3.8 → 0.3.9

package/dist/attach-fencing.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Attach fencing (RT-N3): the boundary between "content this run watched happen"
+ * and "content that already existed when this run started watching it."
+ *
+ * Both `orchestrator/src/attach-to-running-process.ts` and this package's own
+ * `attachManagedProcess` read a target's ENTIRE log file on every poll —
+ * necessary, since a plain file offers no delta API — which means the very
+ * first read hands back everything the target had already written before
+ * attach, indistinguishable from something that happens during this run
+ * unless something records the boundary.
+ *
+ * Real incident (`documents/plans/descry-uat-phase-4.md`, finding N3): a
+ * killed, orphaned FIRST process took its full timeout to exit and kept
+ * writing to the SAME log path a SECOND, successful process also used;
+ * attaching to the second process's pid read the first process's crash as if
+ * it were the second's own. Two independent fences close two independent
+ * parts of that gap:
+ *
+ * - `computeAttachFence` records, at the moment of attach, how much of the
+ *   log file already existed (`attachOffsetBytes`, `preExistingLineCount`)
+ *   and the target's own process start time (best-effort, Linux only) — the
+ *   information a caller needs to mark already-written content instead of
+ *   treating it as freshly observed.
+ * - `detectOtherLogWriters` answers a different question: is some OTHER
+ *   process, right now, also holding this same log file open for writing?
+ *   On Linux only, by scanning `/proc/*\/fd`. A genuinely shared log (e.g. a
+ *   `docker compose` stack's combined stream) is a legitimate answer here,
+ *   not refused — this function reports who else has the file open, and it
+ *   is the caller's job to decide what that means for a given target.
+ *
+ * Neither function makes attach perfectly correct — a log file carries no
+ * per-line writer-pid metadata, so "verify every line against the declared
+ * pid" is not implementable over a plain text file. What these two give a
+ * caller together: the boundary of what this run actually watched happen,
+ * and a best-effort, honestly-labelled answer to "is anything else writing
+ * here right now."
+ */
+export type ProcessStartTimeResult = {
+    readonly ok: true;
+    readonly startTimeMs: number;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * `pid`'s own start time, as wall-clock epoch milliseconds — Linux only.
+ * `/proc/<pid>/stat` field 22 (`starttime`) is clock ticks since boot, not
+ * since epoch; converted via `/proc/uptime`'s boot-relative uptime, itself
+ * converted to an epoch instant from `Date.now()` at read time (so this is
+ * only as precise as the gap between the two reads, sub-millisecond in
+ * practice).
+ *
+ * The `comm` field (`/proc/pid/stat` field 2) can itself contain spaces and
+ * parentheses — parsed by finding the LAST `)` on the line, matching every
+ * real `/proc/pid/stat` parser: the kernel guarantees the true comm field
+ * ends at the last `)`, whatever it contains.
+ */
+export declare function getProcessStartTimeMs(pid: number, platform?: NodeJS.Platform): ProcessStartTimeResult;
+export type OtherLogWriterCheck = {
+    readonly checked: true;
+    readonly otherWriterPids: readonly number[];
+} | {
+    readonly checked: false;
+    readonly reason: string;
+};
+/**
+ * Every OTHER process (not `targetPid`) currently holding an open file
+ * descriptor to `logFilePath`, by scanning `/proc/*\/fd` and comparing each
+ * descriptor's real target against `logFilePath`'s own real path. Linux only.
+ *
+ * A non-empty result is not by itself a problem — a deliberately shared log
+ * (several processes in one `docker compose` stack writing one combined
+ * stream) is legitimate multi-writer use. This function only answers "who
+ * else has it open right now"; a caller decides what that means for a given
+ * target.
+ *
+ * `checked: false` (never a thrown exception) only for what stops the scan
+ * from running AT ALL: non-Linux, `/proc` itself unreadable, or the log path
+ * can't be resolved to a real path. A single pid's `/proc/<pid>/fd` being
+ * unreadable (exited mid-scan, or a permission boundary) is NOT that —
+ * skipped for that one pid only, the same benign-race tolerance
+ * `inferRespawnCommandFromProc` already applies to `/proc` reads elsewhere
+ * in this codebase.
+ */
+export declare function detectOtherLogWriters(logFilePath: string, targetPid: number, platform?: NodeJS.Platform): OtherLogWriterCheck;
+export interface AttachFence {
+    /** The log file's size in bytes at the moment of attach — rotation detection compares this (or a later high-water mark) against the file's current size. */
+    readonly attachOffsetBytes: number;
+    /**
+     * How many complete lines already existed in the log file at the moment of
+     * attach. A source that yields lines in file order marks the first
+     * this-many `preExisting: true`. See `countCompleteLines` for the one
+     * disclosed edge case (a line torn exactly at the attach instant).
+     */
+    readonly preExistingLineCount: number;
+    /** Best-effort, Linux-only; `ok: false` on any other platform or read failure — never blocks the attach itself. */
+    readonly processStartTime: ProcessStartTimeResult;
+    /** See `detectOtherLogWriters` — computed once, at the moment of attach, against the pid this fence was built for. */
+    readonly otherWriters: OtherLogWriterCheck;
+    readonly attachedAt: string;
+}
+/**
+ * Snapshots the fence at the moment of attach. Never throws: a log file that
+ * doesn't exist yet at attach time (a target that hasn't written anything) is
+ * an honest zero-backlog fence, not an error — the file-tail machinery
+ * downstream already tolerates a not-yet-existing path the same way.
+ */
+export declare function computeAttachFence(pid: number, logFilePath: string, platform?: NodeJS.Platform): AttachFence;
+//# sourceMappingURL=attach-fencing.d.ts.map

package/dist/attach-fencing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach-fencing.d.ts","sourceRoot":"","sources":["../src/attach-fencing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAsBH,MAAM,MAAM,sBAAsB,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAwB3I;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,sBAAsB,CAiCvH;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACvE;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,mBAAmB,CA+C/I;AAED,MAAM,WAAW,WAAW;IAC1B,4JAA4J;IAC5J,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,mHAAmH;IACnH,QAAQ,CAAC,gBAAgB,EAAE,sBAAsB,CAAC;IAClD,sHAAsH;IACtH,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,WAAW,CAgB9H"}

package/dist/attach-fencing.js

@@ -0,0 +1,215 @@
+/**
+ * Attach fencing (RT-N3): the boundary between "content this run watched happen"
+ * and "content that already existed when this run started watching it."
+ *
+ * Both `orchestrator/src/attach-to-running-process.ts` and this package's own
+ * `attachManagedProcess` read a target's ENTIRE log file on every poll —
+ * necessary, since a plain file offers no delta API — which means the very
+ * first read hands back everything the target had already written before
+ * attach, indistinguishable from something that happens during this run
+ * unless something records the boundary.
+ *
+ * Real incident (`documents/plans/descry-uat-phase-4.md`, finding N3): a
+ * killed, orphaned FIRST process took its full timeout to exit and kept
+ * writing to the SAME log path a SECOND, successful process also used;
+ * attaching to the second process's pid read the first process's crash as if
+ * it were the second's own. Two independent fences close two independent
+ * parts of that gap:
+ *
+ * - `computeAttachFence` records, at the moment of attach, how much of the
+ *   log file already existed (`attachOffsetBytes`, `preExistingLineCount`)
+ *   and the target's own process start time (best-effort, Linux only) — the
+ *   information a caller needs to mark already-written content instead of
+ *   treating it as freshly observed.
+ * - `detectOtherLogWriters` answers a different question: is some OTHER
+ *   process, right now, also holding this same log file open for writing?
+ *   On Linux only, by scanning `/proc/*\/fd`. A genuinely shared log (e.g. a
+ *   `docker compose` stack's combined stream) is a legitimate answer here,
+ *   not refused — this function reports who else has the file open, and it
+ *   is the caller's job to decide what that means for a given target.
+ *
+ * Neither function makes attach perfectly correct — a log file carries no
+ * per-line writer-pid metadata, so "verify every line against the declared
+ * pid" is not implementable over a plain text file. What these two give a
+ * caller together: the boundary of what this run actually watched happen,
+ * and a best-effort, honestly-labelled answer to "is anything else writing
+ * here right now."
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync, readdirSync, readlinkSync, realpathSync, statSync } from "node:fs";
+/**
+ * Complete (newline-terminated) lines in `text` — the same rule `LineSplitter`
+ * (`@descryy/runtime-backend-observation`) applies, reimplemented here rather
+ * than imported: this package does not depend on that one (the dependency
+ * runs the other way), and the rule is three lines. A trailing, unterminated
+ * partial line is deliberately NOT counted — see `computeAttachFence`'s doc
+ * for the one edge case that leaves disclosed rather than solved.
+ */
+function countCompleteLines(text) {
+    if (text === "")
+        return 0;
+    const parts = text.split(/\r\n|\r|\n/);
+    // split() always yields at least one element; the LAST one is whatever
+    // followed the final terminator (empty, when text ends with one — itself
+    // not a line — or a real trailing partial otherwise; neither is counted).
+    return parts.length - 1;
+}
+let cachedClockTicksPerSecond = null;
+/**
+ * `sysconf(_SC_CLK_TCK)` has no Node binding; `getconf CLK_TCK` is the same
+ * syscall via the POSIX utility every Linux ships. Cached process-wide — it
+ * cannot change while this process runs. Falls back to 100 (`USER_HZ`, the
+ * value on every Linux kernel/architecture this has been measured against)
+ * if `getconf` itself is unavailable, rather than failing the whole
+ * start-time computation over a missing convenience binary.
+ */
+function clockTicksPerSecond() {
+    if (cachedClockTicksPerSecond !== null)
+        return cachedClockTicksPerSecond;
+    try {
+        const output = execFileSync("getconf", ["CLK_TCK"], { encoding: "utf8" }).trim();
+        const parsed = Number(output);
+        cachedClockTicksPerSecond = Number.isFinite(parsed) && parsed > 0 ? parsed : 100;
+    }
+    catch {
+        cachedClockTicksPerSecond = 100;
+    }
+    return cachedClockTicksPerSecond;
+}
+/**
+ * `pid`'s own start time, as wall-clock epoch milliseconds — Linux only.
+ * `/proc/<pid>/stat` field 22 (`starttime`) is clock ticks since boot, not
+ * since epoch; converted via `/proc/uptime`'s boot-relative uptime, itself
+ * converted to an epoch instant from `Date.now()` at read time (so this is
+ * only as precise as the gap between the two reads, sub-millisecond in
+ * practice).
+ *
+ * The `comm` field (`/proc/pid/stat` field 2) can itself contain spaces and
+ * parentheses — parsed by finding the LAST `)` on the line, matching every
+ * real `/proc/pid/stat` parser: the kernel guarantees the true comm field
+ * ends at the last `)`, whatever it contains.
+ */
+export function getProcessStartTimeMs(pid, platform = process.platform) {
+    if (platform !== "linux") {
+        return { ok: false, reason: `process start time via /proc is Linux-only; not available on "${platform}"` };
+    }
+    let statLine;
+    try {
+        statLine = readFileSync(`/proc/${String(pid)}/stat`, "utf8");
+    }
+    catch (error) {
+        return { ok: false, reason: `could not read /proc/${String(pid)}/stat: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    const afterComm = statLine.slice(statLine.lastIndexOf(")") + 1).trim();
+    const fields = afterComm.split(/\s+/);
+    // field 1 of `afterComm` is /proc/pid/stat's field 3 (state); starttime is
+    // field 22 overall, i.e. index 19 in this zero-indexed, comm-stripped array.
+    const starttimeTicks = Number(fields[19]);
+    if (!Number.isFinite(starttimeTicks)) {
+        return { ok: false, reason: `/proc/${String(pid)}/stat did not parse as expected — starttime field missing or non-numeric` };
+    }
+    let uptimeSeconds;
+    try {
+        const uptimeRaw = readFileSync("/proc/uptime", "utf8").trim().split(/\s+/)[0];
+        uptimeSeconds = Number(uptimeRaw);
+        if (!Number.isFinite(uptimeSeconds))
+            throw new Error("non-numeric");
+    }
+    catch (error) {
+        return { ok: false, reason: `could not read /proc/uptime to convert starttime to wall-clock time: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    const bootEpochMs = Date.now() - uptimeSeconds * 1000;
+    const startTimeMs = bootEpochMs + (starttimeTicks / clockTicksPerSecond()) * 1000;
+    return { ok: true, startTimeMs };
+}
+/**
+ * Every OTHER process (not `targetPid`) currently holding an open file
+ * descriptor to `logFilePath`, by scanning `/proc/*\/fd` and comparing each
+ * descriptor's real target against `logFilePath`'s own real path. Linux only.
+ *
+ * A non-empty result is not by itself a problem — a deliberately shared log
+ * (several processes in one `docker compose` stack writing one combined
+ * stream) is legitimate multi-writer use. This function only answers "who
+ * else has it open right now"; a caller decides what that means for a given
+ * target.
+ *
+ * `checked: false` (never a thrown exception) only for what stops the scan
+ * from running AT ALL: non-Linux, `/proc` itself unreadable, or the log path
+ * can't be resolved to a real path. A single pid's `/proc/<pid>/fd` being
+ * unreadable (exited mid-scan, or a permission boundary) is NOT that —
+ * skipped for that one pid only, the same benign-race tolerance
+ * `inferRespawnCommandFromProc` already applies to `/proc` reads elsewhere
+ * in this codebase.
+ */
+export function detectOtherLogWriters(logFilePath, targetPid, platform = process.platform) {
+    if (platform !== "linux") {
+        return { checked: false, reason: `second-writer detection requires scanning /proc/*/fd, which is Linux-only; not available on "${platform}"` };
+    }
+    let target;
+    try {
+        target = realpathSync(logFilePath);
+    }
+    catch (error) {
+        return {
+            checked: false,
+            reason: `could not resolve a real path for "${logFilePath}" to compare against other processes' open file descriptors: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    let pidEntries;
+    try {
+        pidEntries = readdirSync("/proc").filter((entry) => /^\d+$/.test(entry));
+    }
+    catch (error) {
+        return { checked: false, reason: `could not list /proc to scan for other processes holding "${logFilePath}" open: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    const otherWriterPids = [];
+    for (const entry of pidEntries) {
+        const pid = Number(entry);
+        if (pid === targetPid)
+            continue; // the attached target itself is expected to hold it open -- not "other"
+        let fds;
+        try {
+            fds = readdirSync(`/proc/${entry}/fd`);
+        }
+        catch {
+            continue; // exited mid-scan, or no permission -- a benign race, not this scan's failure
+        }
+        for (const fd of fds) {
+            try {
+                if (readlinkSync(`/proc/${entry}/fd/${fd}`) === target) {
+                    otherWriterPids.push(pid);
+                    break;
+                }
+            }
+            catch {
+                // fd closed between readdir and readlink -- benign race, skip
+            }
+        }
+    }
+    return { checked: true, otherWriterPids };
+}
+/**
+ * Snapshots the fence at the moment of attach. Never throws: a log file that
+ * doesn't exist yet at attach time (a target that hasn't written anything) is
+ * an honest zero-backlog fence, not an error — the file-tail machinery
+ * downstream already tolerates a not-yet-existing path the same way.
+ */
+export function computeAttachFence(pid, logFilePath, platform = process.platform) {
+    let attachOffsetBytes = 0;
+    let preExistingLineCount = 0;
+    try {
+        attachOffsetBytes = statSync(logFilePath).size;
+        preExistingLineCount = countCompleteLines(readFileSync(logFilePath, "utf8"));
+    }
+    catch {
+        // Not yet created -- nothing pre-existing, the honest default.
+    }
+    return {
+        attachOffsetBytes,
+        preExistingLineCount,
+        processStartTime: getProcessStartTimeMs(pid, platform),
+        otherWriters: detectOtherLogWriters(logFilePath, pid, platform),
+        attachedAt: new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=attach-fencing.js.map

package/dist/attach-fencing.js.map

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

package/dist/capability-registry.d.ts

@@ -0,0 +1,9 @@
+import type { CapabilityStatus, CollectorCapabilities, EnvironmentTier, ExecutionCapabilities, FidelityLevel } from "@descryy/runtime-contracts";
+export interface RegisteredCollectorCapabilities {
+    readonly collectorId: string;
+    readonly capabilities: CollectorCapabilities;
+}
+export declare function buildExecutionCapabilities(environmentTier: EnvironmentTier, fidelityLevel: FidelityLevel, collectors: readonly RegisteredCollectorCapabilities[]): ExecutionCapabilities;
+export type CollectorCapabilityKey = keyof CollectorCapabilities;
+export declare function bestCapabilityStatus(capabilities: ExecutionCapabilities, key: CollectorCapabilityKey): CapabilityStatus;
+//# sourceMappingURL=capability-registry.d.ts.map

package/dist/capability-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-registry.d.ts","sourceRoot":"","sources":["../src/capability-registry.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAEV,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EACf,qBAAqB,EACrB,aAAa,EACd,MAAM,4BAA4B,CAAC;AAEpC,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,qBAAqB,CAAC;CAC9C;AAED,wBAAgB,0BAA0B,CACxC,eAAe,EAAE,eAAe,EAChC,aAAa,EAAE,aAAa,EAC5B,UAAU,EAAE,SAAS,+BAA+B,EAAE,GACrD,qBAAqB,CAEvB;AAED,MAAM,MAAM,sBAAsB,GAAG,MAAM,qBAAqB,CAAC;AAgBjE,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,qBAAqB,EACnC,GAAG,EAAE,sBAAsB,GAC1B,gBAAgB,CAWlB"}

package/dist/capability-registry.js

@@ -0,0 +1,32 @@
+// Capability registry (§16): assembles per-execution capabilities from the collectors
+// actually present, so e.g. `distributedTrace: unavailable` is a first-class answer
+// rather than a silent gap. Assembles and queries only — producing a
+// `CollectorCapabilities` value is each collector's own `capabilities()`.
+export function buildExecutionCapabilities(environmentTier, fidelityLevel, collectors) {
+    return { environmentTier, fidelityLevel, collectors };
+}
+const AVAILABILITY_RANK = {
+    unavailable: 0,
+    degraded: 1,
+    available: 2,
+};
+const NO_COLLECTOR_STATUS = {
+    availability: "unavailable",
+    reason: "no collector registered for this execution",
+};
+// Best (most available) status for one capability across all registered collectors —
+// "observable anywhere in this execution," not per-collector: two network collectors,
+// one degraded one available, should read as available.
+export function bestCapabilityStatus(capabilities, key) {
+    // Seeded from the first collector seen, not NO_COLLECTOR_STATUS — seeding from the
+    // placeholder would let a real "unavailable" tie the placeholder and lose its reason.
+    let best = null;
+    for (const collector of capabilities.collectors) {
+        const status = collector.capabilities[key];
+        if (best === null || AVAILABILITY_RANK[status.availability] > AVAILABILITY_RANK[best.availability]) {
+            best = status;
+        }
+    }
+    return best ?? NO_COLLECTOR_STATUS;
+}
+//# sourceMappingURL=capability-registry.js.map

package/dist/capability-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-registry.js","sourceRoot":"","sources":["../src/capability-registry.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,oFAAoF;AACpF,qEAAqE;AACrE,0EAA0E;AAgB1E,MAAM,UAAU,0BAA0B,CACxC,eAAgC,EAChC,aAA4B,EAC5B,UAAsD;IAEtD,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,UAAU,EAAE,CAAC;AACxD,CAAC;AAID,MAAM,iBAAiB,GAAqD;IAC1E,WAAW,EAAE,CAAC;IACd,QAAQ,EAAE,CAAC;IACX,SAAS,EAAE,CAAC;CACb,CAAC;AAEF,MAAM,mBAAmB,GAAqB;IAC5C,YAAY,EAAE,aAAa;IAC3B,MAAM,EAAE,4CAA4C;CACrD,CAAC;AAEF,qFAAqF;AACrF,sFAAsF;AACtF,wDAAwD;AACxD,MAAM,UAAU,oBAAoB,CAClC,YAAmC,EACnC,GAA2B;IAE3B,mFAAmF;IACnF,sFAAsF;IACtF,IAAI,IAAI,GAA4B,IAAI,CAAC;IACzC,KAAK,MAAM,SAAS,IAAI,YAAY,CAAC,UAAU,EAAE,CAAC;QAChD,MAAM,MAAM,GAAG,SAAS,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;QAC3C,IAAI,IAAI,KAAK,IAAI,IAAI,iBAAiB,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,iBAAiB,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;YACnG,IAAI,GAAG,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IACD,OAAO,IAAI,IAAI,mBAAmB,CAAC;AACrC,CAAC"}

package/dist/collector-version.d.ts

@@ -0,0 +1,3 @@
+/** `Evidence.collectorVersion` for `ProcessCollector`: read from package.json itself so it can't drift from what shipped. Same pattern as `nodeVersion` (`process.version`), applied to a package instead of the runtime. */
+export declare const COLLECTOR_VERSION: string;
+//# sourceMappingURL=collector-version.d.ts.map

package/dist/collector-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector-version.d.ts","sourceRoot":"","sources":["../src/collector-version.ts"],"names":[],"mappings":"AAAA,6NAA6N;AAM7N,eAAO,MAAM,iBAAiB,EAAE,MAA6E,CAAC"}

package/dist/collector-version.js

@@ -0,0 +1,5 @@
+/** `Evidence.collectorVersion` for `ProcessCollector`: read from package.json itself so it can't drift from what shipped. Same pattern as `nodeVersion` (`process.version`), applied to a package instead of the runtime. */
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+export const COLLECTOR_VERSION = require("../package.json").version;
+//# sourceMappingURL=collector-version.js.map

package/dist/collector-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector-version.js","sourceRoot":"","sources":["../src/collector-version.ts"],"names":[],"mappings":"AAAA,6NAA6N;AAE7N,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAE/C,MAAM,CAAC,MAAM,iBAAiB,GAAY,OAAO,CAAC,iBAAiB,CAAkC,CAAC,OAAO,CAAC"}

package/dist/container-sandbox.d.ts

@@ -0,0 +1,104 @@
+/**
+ * §21's execution boundary, container backend -- the macOS/Windows half of the
+ * sandbox-isolation lane (`sandbox.ts` covers Linux via bubblewrap).
+ *
+ * **Not a second native sandbox.** `sandbox-exec`/Seatbelt (macOS) and Job
+ * Objects/AppContainer/WFP (Windows) were researched and rejected: `sandbox-exec` is
+ * deprecated with no public API replacement, Endpoint Security needs an Apple
+ * entitlement this project doesn't have, and hand-building Windows equivalents is a
+ * second and third bespoke sandbox for a problem already solved once.
+ *
+ * **Mechanism: route the spawned process through a real container instead**, via
+ * `docker run` (Docker Desktop's Linux VM on macOS, WSL2/Docker Desktop on Windows).
+ * The container's own rootfs is the isolation boundary; no bwrap needed inside it.
+ *
+ * **Verified for real** (Linux dev machine, real Docker daemon 29.6.1, not mocked):
+ * a file outside bind-mounts is unreachable (`ENOENT`); a network call under
+ * `--network none` is refused against a real listener; both together, through the
+ * full `ExecutionController.run()` path. See `container-sandbox.test.ts`,
+ * `controller.test.ts`'s container-backend e2e test.
+ *
+ * **UNVERIFIED on real macOS/Windows hardware** (none available here): Docker
+ * Desktop running-detection before spawn, path translation across the Docker
+ * Desktop VM boundary (macOS) and WSL2 (Windows) -- this module's bind-mount assumes
+ * host path == in-container path (`-v hostPath:hostPath`), true on Linux and for
+ * Docker Desktop's Linux VM when already inside its shared-drive mapping, untested
+ * for an arbitrary Windows path. Mechanism exists and is tested where it can be;
+ * cross-platform verification needs hardware nobody here has -- not a bug, not
+ * claimed otherwise.
+ *
+ * **Scope boundary** (same treatment as attach-mode elsewhere): a target that can't
+ * run containerized at all (deep native OS integration, GUI, native deps absent
+ * from a Linux image) is out of scope on any platform, with no native-sandbox
+ * fallback -- disclosed, not silently unsupported.
+ *
+ * **Measured Docker/bwrap difference** (found via a mutation check removing
+ * `--network none` and rerunning): Docker gives every container its own network
+ * namespace regardless of `--network none` -- unlike bwrap, which shares the host's
+ * network unless `networkPolicy` is declared. So a container can never reach the
+ * HOST's loopback either way, but it CAN still reach the public internet via
+ * Docker's default bridge NAT unless `--network none` is set. The dedicated
+ * mutation-sensitive test in `container-sandbox.test.ts` checks reachability to an
+ * external host (not loopback) to isolate exactly this.
+ *
+ * **Not solved here, disclosed:** `ResourceLimits` composition -- `sandbox.ts` wraps
+ * bwrap with `applyResourceLimits`; this module does not wrap Docker's
+ * `--memory`/`--cpus`/`--pids-limit` equivalents, so a `resourceLimits`-declared
+ * execution on this backend runs unlimited inside the container. Selective network
+ * allow/deny-listing is unimplemented for the same reason as `sandbox.ts` (needs DNS
+ * interception + IP filtering) -- `unsupportedContainerNetworkPolicyReason` reports
+ * it the same way, matching posture rather than overclaiming.
+ */
+import type { CapabilityStatus, FilesystemPolicy, NetworkPolicy } from "@descryy/runtime-contracts";
+/** Real check: working Docker CLI + reachable daemon, not just a `docker` binary on PATH. `docker version` talks to the daemon, so a CLI with no daemon running fails the same way a missing binary does -- both mean "cannot enforce." */
+export declare function containerRuntimeCapability(env?: NodeJS.ProcessEnv): CapabilityStatus;
+export declare function containerFilesystemIsolationCapability(env?: NodeJS.ProcessEnv): CapabilityStatus;
+export declare function containerNetworkIsolationCapability(env?: NodeJS.ProcessEnv): CapabilityStatus;
+/** Same posture as `sandbox.ts`'s `unsupportedNetworkPolicyReason`: only full denial (`--network none`) is enforced. A shape bwrap discloses as unsupported isn't silently claimed here just because the mechanism changed. */
+export declare function unsupportedContainerNetworkPolicyReason(policy: NetworkPolicy): string | null;
+export declare function resolveContainerImage(interpreterCommand: string): string | null;
+export interface ContainerSandboxOptions {
+    /** Resolves a default base image via `resolveContainerImage` when `containerImage` is not given. */
+    readonly interpreterCommand: string;
+    /** Command to exec inside the container -- resolved against the image's own PATH, not the host's. */
+    readonly command: string;
+    readonly args: readonly string[];
+    /** Always bind-mounted at the identical path (`-v cwd:cwd`) -- mirrors sandbox.ts's "cwd always bound" default. */
+    readonly cwd: string;
+    readonly filesystemPolicy?: FilesystemPolicy;
+    readonly networkPolicy?: NetworkPolicy;
+    /**
+     * Env vars the containerized process needs, forwarded via `-e KEY=VALUE`. `PATH` is
+     * never forwarded: the container must resolve `command` against its own image
+     * layout (`/usr/local/bin/node`, not the host's), and the host's PATH would break
+     * that or run the wrong binary. Everything else forwards unfiltered, matching
+     * bwrap's own unfiltered-inheritance precedent (no `--clearenv`).
+     */
+    readonly processEnv?: Readonly<Record<string, string | undefined>>;
+    /** Env for running the `docker` CLI itself (PATH, `DOCKER_HOST`). Defaults to `process.env`. */
+    readonly env?: NodeJS.ProcessEnv;
+    /** Explicit override, bypasses `resolveContainerImage`'s name-based guess. */
+    readonly containerImage?: string;
+}
+/**
+ * Wraps `command`/`args` with `docker run` so a container boundary enforces
+ * `filesystemPolicy`/`networkPolicy`. Neither declared returns them unchanged and
+ * never invokes docker -- same non-regression contract as `sandbox.ts`'s
+ * `applySandbox`.
+ *
+ * **Throws rather than silently spawning unconstrained** when a policy can't
+ * actually be backed (no working Docker, unimplemented `networkPolicy` shape).
+ *
+ * **Returns a real, unique `containerName` whenever it wraps.** Found via real
+ * escape testing: `process-manager.ts`'s group-kill targets the local `docker` CLI
+ * process's group, which is right for bwrap but not Docker -- the container runs
+ * under `dockerd`, not as the CLI's child, so killing the CLI's group left an
+ * orphaned `node:22-slim` container running in testing. `containerName` lets the
+ * caller issue an explicit `docker stop <name>` against the container itself.
+ */
+export declare function applyContainerSandbox(options: ContainerSandboxOptions): {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly containerName?: string;
+};
+//# sourceMappingURL=container-sandbox.d.ts.map

package/dist/container-sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"container-sandbox.d.ts","sourceRoot":"","sources":["../src/container-sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEpG,2OAA2O;AAC3O,wBAAgB,0BAA0B,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,gBAAgB,CAUjG;AAKD,wBAAgB,sCAAsC,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,gBAAgB,CAE7G;AAED,wBAAgB,mCAAmC,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,gBAAgB,CAE1G;AAED,+NAA+N;AAC/N,wBAAgB,uCAAuC,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAO5F;AAYD,wBAAgB,qBAAqB,CAAC,kBAAkB,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE/E;AAED,MAAM,WAAW,uBAAuB;IACtC,oGAAoG;IACpG,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,qGAAqG;IACrG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,mHAAmH;IACnH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAC7C,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IACnE,gGAAgG;IAChG,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,uBAAuB,GAC/B;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,CAkDjG"}