@descryy/runtime-controller 0.3.8 → 0.4.0

package/dist/dependency-version-check.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `DEC-NEXT-fault-layer-empirical-confirmation.md`'s `dependency` mechanism: declared
+ * (lockfile) vs resolved (installed) version — a structural fact, recorded not inferred.
+ *
+ * - Node-only, checked not assumed: no existing lockfile reader for any language to
+ *   match. A Python/Ruby target is a real, disclosed gap — an additive second reader,
+ *   not a rewrite.
+ * - Only `lockfileVersion` 2/3's flat `packages` map (keyed by `node_modules/<name>`,
+ *   confirmed against `fixture-apps/broken-invoices-backend`). v1's `dependencies`
+ *   shape is not read — `applicable: false`, disclosed gap.
+ * - "Resolved" is a direct read from the lockfile key's path, not Node module
+ *   resolution — the key already encodes install location, including nested
+ *   transitives (`node_modules/a/node_modules/b`).
+ * - Direct dependencies only (`dependencies`/`devDependencies`), not every transitive
+ *   lockfile entry — matches the ruling's "cheap, always available" bar.
+ */
+export interface DependencyVersionMismatch {
+    readonly name: string;
+    /** The version `package-lock.json` pins this package to. */
+    readonly declaredVersion: string;
+    /** The version actually found in `node_modules/<name>/package.json` on disk. */
+    readonly resolvedVersion: string;
+}
+export interface DependencyVersionCheckResult {
+    /** `false` when not identifiable as a checkable Node target (no package.json/lockfile, unsupported shape, malformed JSON) — "not applicable", not a guessed clean result. `mismatches` is `[]` when `false`. */
+    readonly applicable: boolean;
+    readonly mismatches: readonly DependencyVersionMismatch[];
+}
+/**
+ * Compares lockfile-declared vs installed version for every direct dependency of the
+ * Node project rooted at `cwd`. A dependency missing from the lockfile (workspace/
+ * local-link) or from `node_modules` (never installed) is skipped, not reported —
+ * different facts from a mismatch, not guessed as one.
+ */
+export declare function checkDependencyVersions(cwd: string): DependencyVersionCheckResult;
+//# sourceMappingURL=dependency-version-check.d.ts.map

package/dist/dependency-version-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependency-version-check.d.ts","sourceRoot":"","sources":["../src/dependency-version-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,gFAAgF;IAChF,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,4BAA4B;IAC3C,gNAAgN;IAChN,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,SAAS,yBAAyB,EAAE,CAAC;CAC3D;AAuBD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,4BAA4B,CA4CjF"}

package/dist/dependency-version-check.js

@@ -0,0 +1,72 @@
+/**
+ * `DEC-NEXT-fault-layer-empirical-confirmation.md`'s `dependency` mechanism: declared
+ * (lockfile) vs resolved (installed) version — a structural fact, recorded not inferred.
+ *
+ * - Node-only, checked not assumed: no existing lockfile reader for any language to
+ *   match. A Python/Ruby target is a real, disclosed gap — an additive second reader,
+ *   not a rewrite.
+ * - Only `lockfileVersion` 2/3's flat `packages` map (keyed by `node_modules/<name>`,
+ *   confirmed against `fixture-apps/broken-invoices-backend`). v1's `dependencies`
+ *   shape is not read — `applicable: false`, disclosed gap.
+ * - "Resolved" is a direct read from the lockfile key's path, not Node module
+ *   resolution — the key already encodes install location, including nested
+ *   transitives (`node_modules/a/node_modules/b`).
+ * - Direct dependencies only (`dependencies`/`devDependencies`), not every transitive
+ *   lockfile entry — matches the ruling's "cheap, always available" bar.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+function readJsonFile(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compares lockfile-declared vs installed version for every direct dependency of the
+ * Node project rooted at `cwd`. A dependency missing from the lockfile (workspace/
+ * local-link) or from `node_modules` (never installed) is skipped, not reported —
+ * different facts from a mismatch, not guessed as one.
+ */
+export function checkDependencyVersions(cwd) {
+    const packageJsonPath = join(cwd, "package.json");
+    const lockfilePath = join(cwd, "package-lock.json");
+    if (!existsSync(packageJsonPath) || !existsSync(lockfilePath)) {
+        return { applicable: false, mismatches: [] };
+    }
+    const packageJson = readJsonFile(packageJsonPath);
+    const lockfile = readJsonFile(lockfilePath);
+    if (packageJson === null || lockfile === null) {
+        return { applicable: false, mismatches: [] };
+    }
+    const packages = lockfile.packages;
+    if (packages === undefined || typeof packages !== "object") {
+        // lockfileVersion 1, or an unrecognized shape -- see header.
+        return { applicable: false, mismatches: [] };
+    }
+    const declaredNames = new Set([
+        ...Object.keys(packageJson.dependencies ?? {}),
+        ...Object.keys(packageJson.devDependencies ?? {}),
+    ]);
+    const mismatches = [];
+    for (const name of declaredNames) {
+        const lockEntry = packages[`node_modules/${name}`];
+        const declaredVersion = lockEntry?.version;
+        if (typeof declaredVersion !== "string")
+            continue;
+        const installedPackageJsonPath = join(cwd, "node_modules", name, "package.json");
+        if (!existsSync(installedPackageJsonPath))
+            continue;
+        const installedPackageJson = readJsonFile(installedPackageJsonPath);
+        const resolvedVersion = installedPackageJson?.version;
+        if (typeof resolvedVersion !== "string")
+            continue;
+        if (resolvedVersion !== declaredVersion) {
+            mismatches.push({ name, declaredVersion, resolvedVersion });
+        }
+    }
+    return { applicable: true, mismatches };
+}
+//# sourceMappingURL=dependency-version-check.js.map

package/dist/dependency-version-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependency-version-check.js","sourceRoot":"","sources":["../src/dependency-version-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AA6BjC,SAAS,YAAY,CAAI,IAAY;IACnC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAM,CAAC;IACrD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAW;IACjD,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;IAClD,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAAC;IAEpD,IAAI,CAAC,UAAU,CAAC,eAAe,CAAC,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAC9D,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;IAC/C,CAAC;IAED,MAAM,WAAW,GAAG,YAAY,CAAmB,eAAe,CAAC,CAAC;IACpE,MAAM,QAAQ,GAAG,YAAY,CAAmB,YAAY,CAAC,CAAC;IAC9D,IAAI,WAAW,KAAK,IAAI,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QAC9C,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;IAC/C,CAAC;IAED,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC;IACnC,IAAI,QAAQ,KAAK,SAAS,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC3D,6DAA6D;QAC7D,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;IAC/C,CAAC;IAED,MAAM,aAAa,GAAG,IAAI,GAAG,CAAS;QACpC,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,YAAY,IAAI,EAAE,CAAC;QAC9C,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,eAAe,IAAI,EAAE,CAAC;KAClD,CAAC,CAAC;IAEH,MAAM,UAAU,GAAgC,EAAE,CAAC;IACnD,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;QACjC,MAAM,SAAS,GAAG,QAAQ,CAAC,gBAAgB,IAAI,EAAE,CAAC,CAAC;QACnD,MAAM,eAAe,GAAG,SAAS,EAAE,OAAO,CAAC;QAC3C,IAAI,OAAO,eAAe,KAAK,QAAQ;YAAE,SAAS;QAElD,MAAM,wBAAwB,GAAG,IAAI,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;QACjF,IAAI,CAAC,UAAU,CAAC,wBAAwB,CAAC;YAAE,SAAS;QAEpD,MAAM,oBAAoB,GAAG,YAAY,CAAgC,wBAAwB,CAAC,CAAC;QACnG,MAAM,eAAe,GAAG,oBAAoB,EAAE,OAAO,CAAC;QACtD,IAAI,OAAO,eAAe,KAAK,QAAQ;YAAE,SAAS;QAElD,IAAI,eAAe,KAAK,eAAe,EAAE,CAAC;YACxC,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,eAAe,EAAE,CAAC,CAAC;QAC9D,CAAC;IACH,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;AAC1C,CAAC"}

package/dist/env.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Default environment applied to every spawned process, on top of the caller's own.
+ *
+ * RUST_BACKTRACE=1 (§17): without it a Rust panic prints only a message, hiding the
+ * trace — a collector-absence-masquerading-as-success case, not a caller-remembers-it case.
+ *
+ * Never overrides a key the caller already set.
+ */
+export declare function withDefaultProcessEnv(env: Readonly<Record<string, string | undefined>>): Record<string, string | undefined>;
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GAChD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAEpC"}

package/dist/env.js

@@ -0,0 +1,12 @@
+/**
+ * Default environment applied to every spawned process, on top of the caller's own.
+ *
+ * RUST_BACKTRACE=1 (§17): without it a Rust panic prints only a message, hiding the
+ * trace — a collector-absence-masquerading-as-success case, not a caller-remembers-it case.
+ *
+ * Never overrides a key the caller already set.
+ */
+export function withDefaultProcessEnv(env) {
+    return { RUST_BACKTRACE: "1", ...env };
+}
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CACnC,GAAiD;IAEjD,OAAO,EAAE,cAAc,EAAE,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC;AACzC,CAAC"}

package/dist/environment-metadata.d.ts

@@ -0,0 +1,15 @@
+/**
+ * §2/RT-193: `Execution.commit` alone can't reproduce a run — same commit, different
+ * Node/OS/toolchain can behave differently. Fills the gap from the real host: OS
+ * platform, this process's own `process.version`, and the version of every distinct
+ * executable `configuration.services` invokes.
+ *
+ * Toolchain probe mirrors `scripts/preflight.mjs`'s `interpreters()` (version flag,
+ * read stdout+stderr combined since some tools like `java -version` write to stderr
+ * only, keep first line) but isn't the same function: that one checks a fixed tool
+ * list against expected versions (a gate); this reports whatever `services[*].command`
+ * names, no expected version to compare against.
+ */
+import type { EnvironmentMetadata, ServiceConfiguration } from "@descryy/runtime-contracts";
+export declare function captureEnvironmentMetadata(services: Readonly<Record<string, ServiceConfiguration>>): Promise<EnvironmentMetadata>;
+//# sourceMappingURL=environment-metadata.d.ts.map

package/dist/environment-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment-metadata.d.ts","sourceRoot":"","sources":["../src/environment-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAM5F,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,GACvD,OAAO,CAAC,mBAAmB,CAAC,CAmB9B"}

package/dist/environment-metadata.js

@@ -0,0 +1,63 @@
+/**
+ * §2/RT-193: `Execution.commit` alone can't reproduce a run — same commit, different
+ * Node/OS/toolchain can behave differently. Fills the gap from the real host: OS
+ * platform, this process's own `process.version`, and the version of every distinct
+ * executable `configuration.services` invokes.
+ *
+ * Toolchain probe mirrors `scripts/preflight.mjs`'s `interpreters()` (version flag,
+ * read stdout+stderr combined since some tools like `java -version` write to stderr
+ * only, keep first line) but isn't the same function: that one checks a fixed tool
+ * list against expected versions (a gate); this reports whatever `services[*].command`
+ * names, no expected version to compare against.
+ */
+import { execFile } from "node:child_process";
+import { platform } from "node:os";
+import { tokenizeCommand } from "./orchestration.js";
+/** Bounds a version probe so a hung command can't stall run() — same discipline as RT-030's readiness probes. */
+const VERSION_PROBE_TIMEOUT_MS = 3000;
+export async function captureEnvironmentMetadata(services) {
+    const commands = new Set();
+    for (const service of Object.values(services)) {
+        // Attach-mode services have no `command` -- nothing to probe.
+        if (service.command === undefined)
+            continue;
+        const tokenized = tokenizeCommand(service.command);
+        if (tokenized.ok)
+            commands.add(tokenized.command);
+    }
+    const toolchainVersions = {};
+    for (const command of commands) {
+        toolchainVersions[command] = await probeVersion(command);
+    }
+    return {
+        platform: platform(),
+        nodeVersion: process.version,
+        toolchainVersions,
+    };
+}
+/** Tries `--version`, `-version`, `-v` in order (covers `java -version`, `mvn -v`, etc). Returns the first line of whichever exits 0, or `null` — an unprobeable command is a disclosed gap, never a thrown error. */
+function probeVersion(command) {
+    return tryFlags(command, ["--version", "-version", "-v"]);
+}
+async function tryFlags(command, flags) {
+    for (const flag of flags) {
+        const output = await runVersionFlag(command, flag);
+        if (output !== null)
+            return output;
+    }
+    return null;
+}
+function runVersionFlag(command, flag) {
+    return new Promise((resolve) => {
+        execFile(command, [flag], { timeout: VERSION_PROBE_TIMEOUT_MS }, (error, stdout, stderr) => {
+            if (error !== null) {
+                resolve(null);
+                return;
+            }
+            const combined = `${stdout}${stderr}`.trim();
+            const firstLine = combined.split("\n")[0];
+            resolve(firstLine === undefined || firstLine === "" ? null : firstLine);
+        });
+    });
+}
+//# sourceMappingURL=environment-metadata.js.map

package/dist/environment-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment-metadata.js","sourceRoot":"","sources":["../src/environment-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD,iHAAiH;AACjH,MAAM,wBAAwB,GAAG,IAAI,CAAC;AAEtC,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,QAAwD;IAExD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9C,8DAA8D;QAC9D,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS;YAAE,SAAS;QAC5C,MAAM,SAAS,GAAG,eAAe,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACnD,IAAI,SAAS,CAAC,EAAE;YAAE,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IACpD,CAAC;IAED,MAAM,iBAAiB,GAAkC,EAAE,CAAC;IAC5D,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,iBAAiB,CAAC,OAAO,CAAC,GAAG,MAAM,YAAY,CAAC,OAAO,CAAC,CAAC;IAC3D,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,QAAQ,EAAE;QACpB,WAAW,EAAE,OAAO,CAAC,OAAO;QAC5B,iBAAiB;KAClB,CAAC;AACJ,CAAC;AAED,sNAAsN;AACtN,SAAS,YAAY,CAAC,OAAe;IACnC,OAAO,QAAQ,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC;AAC5D,CAAC;AAED,KAAK,UAAU,QAAQ,CAAC,OAAe,EAAE,KAAwB;IAC/D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACnD,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,MAAM,CAAC;IACrC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,cAAc,CAAC,OAAe,EAAE,IAAY;IACnD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,EAAE,EAAE,OAAO,EAAE,wBAAwB,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;YACzF,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,OAAO,CAAC,IAAI,CAAC,CAAC;gBACd,OAAO;YACT,CAAC;YACD,MAAM,QAAQ,GAAG,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC;YAC7C,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YAC1C,OAAO,CAAC,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAC1E,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/environment-version-check.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `DEC-NEXT-fault-layer-empirical-confirmation.md`'s `environment` mechanism:
+ * declared/expected runner version vs observed, at execution. Same shape as
+ * `dependency-version-check.ts` -- cheap, always available, no rerun needed.
+ *
+ * - "Declared" reads `.nvmrc`/`package.json engines.node`, not a CI-workflow parser
+ *   -- nothing here already parses CI YAML, and these are the load-bearing
+ *   declarations `nvm`/`npm` themselves read. A future CI-file reader is a
+ *   disclosed extension point: `declaredSource` is a closed union so a third source
+ *   can be added without changing callers' shape.
+ * - `satisfiesDeclaredNodeVersion`'s grammar supports `^x.y.z`, `~x.y.z`,
+ *   `>=`/`<=`/`>`/`<`, a bare version at any precision (x-range at that precision,
+ *   matching `actions/setup-node`), and space-separated AND clauses. Does NOT
+ *   support `||`, hyphen ranges, prerelease/build tags, or `x`/`*` wildcards --
+ *   those parse to `null` ("cannot say"), never a guessed true/false.
+ */
+export declare const DECLARED_VERSION_SOURCES: readonly ["nvmrc", "package.json engines.node"];
+export type DeclaredVersionSource = (typeof DECLARED_VERSION_SOURCES)[number];
+export interface EnvironmentVersionCheckResult {
+    /** `false` when no declared version was found, or declared/observed didn't parse -- "not applicable," never a guessed clean result. `mismatch` is `false` when this is. */
+    readonly applicable: boolean;
+    readonly mismatch: boolean;
+    readonly declaredVersion: string | null;
+    readonly declaredSource: DeclaredVersionSource | null;
+    readonly observedVersion: string;
+}
+/**
+ * Reads the declared Node version for the project at `cwd`, compares against
+ * `observedVersion` (`process.version`/`EnvironmentMetadata.nodeVersion` -- never
+ * probed here).
+ *
+ * `.nvmrc` takes precedence over `engines.node` when both exist -- it names one
+ * exact version a developer runs locally, vs. a more often permissive compatibility
+ * range. Narrower/more specific wins, same precedence `classifyFaultLayer`
+ * (`descry-core`) applies between `dependency` and `environment`.
+ */
+export declare function checkEnvironmentVersion(cwd: string, observedVersion: string): EnvironmentVersionCheckResult;
+/** Whether `observedVersion` satisfies `declaredRange` under the grammar above. `null` means the comparison couldn't be made -- distinct from `false`, a real "does not satisfy" answer. */
+export declare function satisfiesDeclaredNodeVersion(declaredRange: string, observedVersion: string): boolean | null;
+//# sourceMappingURL=environment-version-check.d.ts.map

package/dist/environment-version-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment-version-check.d.ts","sourceRoot":"","sources":["../src/environment-version-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,eAAO,MAAM,wBAAwB,iDAAkD,CAAC;AACxF,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9E,MAAM,WAAW,6BAA6B;IAC5C,2KAA2K;IAC3K,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,cAAc,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACtD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAMD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,6BAA6B,CAgD3G;AAmGD,4LAA4L;AAC5L,wBAAgB,4BAA4B,CAAC,aAAa,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAU3G"}

package/dist/environment-version-check.js

@@ -0,0 +1,176 @@
+/**
+ * `DEC-NEXT-fault-layer-empirical-confirmation.md`'s `environment` mechanism:
+ * declared/expected runner version vs observed, at execution. Same shape as
+ * `dependency-version-check.ts` -- cheap, always available, no rerun needed.
+ *
+ * - "Declared" reads `.nvmrc`/`package.json engines.node`, not a CI-workflow parser
+ *   -- nothing here already parses CI YAML, and these are the load-bearing
+ *   declarations `nvm`/`npm` themselves read. A future CI-file reader is a
+ *   disclosed extension point: `declaredSource` is a closed union so a third source
+ *   can be added without changing callers' shape.
+ * - `satisfiesDeclaredNodeVersion`'s grammar supports `^x.y.z`, `~x.y.z`,
+ *   `>=`/`<=`/`>`/`<`, a bare version at any precision (x-range at that precision,
+ *   matching `actions/setup-node`), and space-separated AND clauses. Does NOT
+ *   support `||`, hyphen ranges, prerelease/build tags, or `x`/`*` wildcards --
+ *   those parse to `null` ("cannot say"), never a guessed true/false.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+export const DECLARED_VERSION_SOURCES = ["nvmrc", "package.json engines.node"];
+/**
+ * Reads the declared Node version for the project at `cwd`, compares against
+ * `observedVersion` (`process.version`/`EnvironmentMetadata.nodeVersion` -- never
+ * probed here).
+ *
+ * `.nvmrc` takes precedence over `engines.node` when both exist -- it names one
+ * exact version a developer runs locally, vs. a more often permissive compatibility
+ * range. Narrower/more specific wins, same precedence `classifyFaultLayer`
+ * (`descry-core`) applies between `dependency` and `environment`.
+ */
+export function checkEnvironmentVersion(cwd, observedVersion) {
+    const notApplicable = {
+        applicable: false,
+        mismatch: false,
+        declaredVersion: null,
+        declaredSource: null,
+        observedVersion,
+    };
+    const nvmrcPath = join(cwd, ".nvmrc");
+    let declaredVersion = null;
+    let declaredSource = null;
+    if (existsSync(nvmrcPath)) {
+        const raw = readFileSync(nvmrcPath, "utf8").trim();
+        if (raw.length > 0) {
+            declaredVersion = raw;
+            declaredSource = "nvmrc";
+        }
+    }
+    else {
+        const packageJsonPath = join(cwd, "package.json");
+        if (existsSync(packageJsonPath)) {
+            let parsed;
+            try {
+                parsed = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+            }
+            catch {
+                parsed = null;
+            }
+            const node = parsed?.engines?.node;
+            if (typeof node === "string" && node.trim().length > 0) {
+                declaredVersion = node;
+                declaredSource = "package.json engines.node";
+            }
+        }
+    }
+    if (declaredVersion === null || declaredSource === null) {
+        return notApplicable;
+    }
+    const satisfies = satisfiesDeclaredNodeVersion(declaredVersion, observedVersion);
+    if (satisfies === null) {
+        // Grammar not covered (or observed string unparseable) -- "not applicable",
+        // not a comparison that was actually made.
+        return { applicable: false, mismatch: false, declaredVersion, declaredSource, observedVersion };
+    }
+    return { applicable: true, mismatch: !satisfies, declaredVersion, declaredSource, observedVersion };
+}
+const VERSION_PATTERN = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?/;
+function parseVersion(raw) {
+    const match = VERSION_PATTERN.exec(raw.trim());
+    if (match === null)
+        return null;
+    const major = Number(match[1]);
+    if (!Number.isFinite(major))
+        return null;
+    return {
+        major,
+        minor: match[2] !== undefined ? Number(match[2]) : 0,
+        minorSpecified: match[2] !== undefined,
+        patch: match[3] !== undefined ? Number(match[3]) : 0,
+        patchSpecified: match[3] !== undefined,
+    };
+}
+/** Positive when `a` > `b`, negative when `a` < `b`, zero when equal -- major.minor.patch only. */
+function compareVersions(a, b) {
+    if (a.major !== b.major)
+        return a.major - b.major;
+    if (a.minor !== b.minor)
+        return a.minor - b.minor;
+    return a.patch - b.patch;
+}
+const CARET_PATTERN = /^\^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/;
+const TILDE_PATTERN = /^~(\d+)(?:\.(\d+))?(?:\.(\d+))?$/;
+const COMPARATOR_PATTERN = /^(>=|<=|>|<|=)?(\d+)(?:\.(\d+))?(?:\.(\d+))?$/;
+/** `null` means the clause's grammar isn't covered -- propagated up, never coerced to a guessed true/false. */
+function satisfiesClause(clause, observed) {
+    const trimmed = clause.trim();
+    if (trimmed.length === 0)
+        return null;
+    const caret = CARET_PATTERN.exec(trimmed);
+    if (caret !== null) {
+        const base = {
+            major: Number(caret[1]),
+            minor: caret[2] !== undefined ? Number(caret[2]) : 0,
+            minorSpecified: true,
+            patch: caret[3] !== undefined ? Number(caret[3]) : 0,
+            patchSpecified: true,
+        };
+        return compareVersions(observed, base) >= 0 && observed.major === base.major;
+    }
+    const tilde = TILDE_PATTERN.exec(trimmed);
+    if (tilde !== null) {
+        const base = {
+            major: Number(tilde[1]),
+            minor: tilde[2] !== undefined ? Number(tilde[2]) : 0,
+            minorSpecified: true,
+            patch: tilde[3] !== undefined ? Number(tilde[3]) : 0,
+            patchSpecified: true,
+        };
+        return compareVersions(observed, base) >= 0 && observed.major === base.major && observed.minor === base.minor;
+    }
+    const comparator = COMPARATOR_PATTERN.exec(trimmed);
+    if (comparator === null)
+        return null;
+    const op = comparator[1];
+    const base = {
+        major: Number(comparator[2]),
+        minor: comparator[3] !== undefined ? Number(comparator[3]) : 0,
+        minorSpecified: comparator[3] !== undefined,
+        patch: comparator[4] !== undefined ? Number(comparator[4]) : 0,
+        patchSpecified: comparator[4] !== undefined,
+    };
+    const cmp = compareVersions(observed, base);
+    switch (op) {
+        case ">=":
+            return cmp >= 0;
+        case "<=":
+            return cmp <= 0;
+        case ">":
+            return cmp > 0;
+        case "<":
+            return cmp < 0;
+        case "=":
+        case undefined:
+            // Bare version: an x-range at whatever precision was actually given.
+            if (!base.minorSpecified)
+                return observed.major === base.major;
+            if (!base.patchSpecified)
+                return observed.major === base.major && observed.minor === base.minor;
+            return cmp === 0;
+        default:
+            return null;
+    }
+}
+/** Whether `observedVersion` satisfies `declaredRange` under the grammar above. `null` means the comparison couldn't be made -- distinct from `false`, a real "does not satisfy" answer. */
+export function satisfiesDeclaredNodeVersion(declaredRange, observedVersion) {
+    const observed = parseVersion(observedVersion);
+    if (observed === null)
+        return null;
+    const clauses = declaredRange.split(/\s+/).filter((clause) => clause.length > 0);
+    if (clauses.length === 0)
+        return null;
+    const results = clauses.map((clause) => satisfiesClause(clause, observed));
+    if (results.some((result) => result === null))
+        return null;
+    return results.every((result) => result === true);
+}
+//# sourceMappingURL=environment-version-check.js.map

package/dist/environment-version-check.js.map

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

package/dist/execution-safety.d.ts

@@ -0,0 +1,96 @@
+/**
+ * §21/RT-070's execution boundary: resource limits and privilege reporting for a
+ * runtime declared trusted-local -- every spawned process runs with the invoking
+ * user's own OS privileges, no filesystem/network restriction. Names the boundary
+ * rather than leaving it absent (§38); real isolation (containers/namespaces) is a
+ * separate decision this module does not invent (§29).
+ *
+ * Enforces for real, via the OS: CPU time, virtual memory, process count, through
+ * `prlimit` -- an exec wrapper, never a shell (a shell would undo RT-036's
+ * `tokenizeCommand` refusal of shell metacharacters). `prlimit` is util-linux, absent
+ * on macOS, so it's reported as a capability, never assumed.
+ */
+import type { CapabilityStatus, ResourceLimits } from "@descryy/runtime-contracts";
+/** Whether `prlimit` is reachable on PATH. `env` is a parameter (default `process.env`) so the "unavailable" branch is testable without mutating the real environment. */
+export declare function resourceLimitCapability(env?: NodeJS.ProcessEnv): CapabilityStatus;
+/**
+ * RT-193 originally made this always `unavailable`. Now delegates to
+ * `networkIsolationCapability()` (`./sandbox.ts`), real on Linux via a bwrap network
+ * namespace -- kept as the stable name every caller already imports (the seam
+ * RT-193 anticipated). Still unconditionally `unavailable` on macOS/Windows.
+ */
+export declare function networkPolicyCapability(env?: NodeJS.ProcessEnv): CapabilityStatus;
+/**
+ * Wraps `command`/`args` so the OS enforces `limits`, via `prlimit`. `undefined` or
+ * empty `limits` returns them unchanged -- opt-in only.
+ *
+ * **Throws rather than silently spawning unconstrained** when a limit was requested
+ * and `prlimit` is unavailable (refuse-not-guess, per RT-036) -- the alternative is a
+ * caller asking for a memory cap and silently getting an unbounded process, the
+ * "sandbox that doesn't sandbox" shape §38 bans.
+ */
+export declare function applyResourceLimits(command: string, args: readonly string[], limits: ResourceLimits | undefined, env?: NodeJS.ProcessEnv): {
+    readonly command: string;
+    readonly args: readonly string[];
+};
+/**
+ * DEC-272: the sandbox boundary (RT-070) must be stated to the user directly, not
+ * left as a silent doc gap. Fixed, not derived from `runningAsRoot` -- the boundary
+ * is the same regardless of privilege level found.
+ *
+ * **Scope: this is the unconditional-unisolated text, not a universal one.** Accurate
+ * for every execution before `sandbox.ts` existed; no longer true once spawn-mode got
+ * real bwrap-backed isolation (`applySandbox`) -- using this unconditionally for an
+ * isolated process would understate its boundary, which is not the safe direction to
+ * be wrong in. `sandboxBoundaryDisclosureFor()` below is the mode-aware replacement;
+ * this constant remains its no-policy-applied return value and attach-mode's own
+ * disclosure (attach-mode never has anything more accurate to say).
+ */
+export declare const SANDBOX_BOUNDARY_DISCLOSURE: string;
+/**
+ * Whether a real policy was actually enforced, not merely requested. `applySandbox`
+ * already throws rather than proceed unconstrained when a declared policy can't be
+ * enforced, so by the time a process is observed running, "declared" and "applied"
+ * are the same fact -- this type makes the caller state it explicitly.
+ */
+export interface AppliedIsolationPolicies {
+    readonly filesystemPolicyApplied: boolean;
+    readonly networkPolicyApplied: boolean;
+}
+/**
+ * Mode-aware replacement for reading `SANDBOX_BOUNDARY_DISCLOSURE` unconditionally.
+ * Defaults to no-policy-applied, so a no-arg call matches the old constant exactly.
+ *
+ * **Only ever true for spawn-mode.** Attach-mode has no path to produce
+ * `filesystemPolicyApplied`/`networkPolicyApplied: true` for a process it didn't
+ * spawn (structural, see `sandbox.ts`) -- attach-mode callers should never pass
+ * anything but the default.
+ */
+export declare function sandboxBoundaryDisclosureFor(policies?: AppliedIsolationPolicies): string;
+/**
+ * Attach mode's contractual scope guarantee -- distinct from the sandbox-boundary
+ * disclosure above: this is what an attach-mode `Collector` is permitted to *do*, not
+ * what OS boundary wraps it. Mirrors `Collector` in `@descryy/runtime-contracts`.
+ * Stated once so every attach-mode caller surfaces the identical sentence.
+ */
+export declare const ATTACH_MODE_SCOPE_DISCLOSURE: string;
+export interface PrivilegeReport {
+    /** Null when the platform has no uid concept (`process.getuid` undefined on Windows) -- distinct from `false`, a real answer. */
+    readonly runningAsRoot: boolean | null;
+    /** DEC-272: plain-language sandbox boundary statement, carried on this result rather than a new return path. Always populated, independent of `runningAsRoot`. */
+    readonly disclosure: string;
+}
+/**
+ * Reports, never enforces. §21's policy for trusted-local (RT-070) is not "refuse to
+ * run as root" -- CI containers commonly do, and a hard refusal would turn a
+ * documented boundary into an undocumented outage. The privilege level just becomes
+ * observable instead of invisible.
+ *
+ * A required parameter, not defaulted: `undefined` is the real value a no-uid-concept
+ * platform produces, and a default can't distinguish "explicitly undefined" from
+ * "omitted." `currentPrivilegeReport()` below is the convenience wrapper; this makes
+ * both branches testable without actually running as root or on Windows.
+ */
+export declare function privilegeReportFor(getuid: (() => number) | undefined): PrivilegeReport;
+export declare function currentPrivilegeReport(): PrivilegeReport;
+//# sourceMappingURL=execution-safety.d.ts.map

package/dist/execution-safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-safety.d.ts","sourceRoot":"","sources":["../src/execution-safety.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAGnF,0KAA0K;AAC1K,wBAAgB,uBAAuB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,gBAAgB,CAU9F;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,gBAAgB,CAE9F;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,EAAE,cAAc,GAAG,SAAS,EAClC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAchE;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,2BAA2B,QAGT,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC;IAC1C,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;CACxC;AAID;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,GAAE,wBAA8C,GAAG,MAAM,CAwB7G;AAED;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,QAKoC,CAAC;AAE9E,MAAM,WAAW,eAAe;IAC9B,iIAAiI;IACjI,QAAQ,CAAC,aAAa,EAAE,OAAO,GAAG,IAAI,CAAC;IACvC,kKAAkK;IAClK,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,GAAG,eAAe,CAGtF;AAED,wBAAgB,sBAAsB,IAAI,eAAe,CAExD"}