@descryy/runtime-controller 0.0.0

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

@@ -0,0 +1,90 @@
+/**
+ * `DEC-NEXT-fault-layer-empirical-confirmation.md`'s `dependency` mechanism:
+ * "declared (lockfile) version vs. resolved (installed) version at
+ * runtime. A mismatch is a structural fact, the same shape as
+ * `automation`'s `harnessFailure` flag — not inferred, recorded."
+ *
+ * ## Node-only, checked rather than assumed
+ *
+ * This repo's own multi-language stance (`CLAUDE.md`: "check what this
+ * repo's existing environment/dependency inspection code, if any, already
+ * assumes about target project types before assuming Node-only") was
+ * checked directly before writing this: `captureEnvironmentMetadata`
+ * (`environment-metadata.ts`, the closest existing thing) probes an
+ * arbitrary command's `--version` output and is genuinely language-agnostic,
+ * but nothing in this repo already reads a *lockfile* for any language --
+ * there was no existing dependency-inspection assumption to match, Node or
+ * otherwise. Node is the one target built here because it is the one the
+ * ruling's own example names (`"lockfile pins left-pad@1.3.0, resolved
+ * 1.2.0"`) and the one every fixture in this repo (`fixture-apps/
+ * broken-invoices-backend`) actually is. A future target (a Python
+ * `requirements.txt`/`pip freeze` pair, a Ruby `Gemfile.lock`) is a real,
+ * disclosed gap -- a second reader function beside this one, not a rewrite
+ * of it, the same "framework extractors are additive" shape
+ * `descry-core`'s own CLAUDE.md describes for its adapters.
+ *
+ * ## Only `lockfileVersion` 2/3's `packages` shape
+ *
+ * Confirmed against this repo's own `fixture-apps/broken-invoices-backend/
+ * package-lock.json` (`lockfileVersion: 3`) rather than assumed: modern npm
+ * writes a flat `packages` map keyed by the `node_modules/<name>` path the
+ * package would be installed at, each entry carrying the resolved
+ * `version` it was locked to -- exactly the "declared" half this function
+ * needs, with no separate resolution algorithm required, because the key
+ * itself already *is* the install path. `lockfileVersion` 1's older
+ * `dependencies` shape is not read here -- `applicable: false`, a
+ * disclosed gap, not a guess dressed up as a second code path.
+ *
+ * ## "Resolved" is a direct read, not `require.resolve`
+ *
+ * The lockfile key (`node_modules/<name>`) is already the exact path this
+ * function reads `package.json` from under the project root. This is
+ * deliberately not Node's own module-resolution algorithm (walking up
+ * successive `node_modules` directories) -- the lockfile key already
+ * encodes exactly where npm decided to place that install, including for a
+ * nested transitive dependency (`node_modules/a/node_modules/b`), and
+ * re-deriving that placement with a resolver would be solving a problem the
+ * lockfile already solved.
+ *
+ * ## Direct dependencies only
+ *
+ * Every name in `package.json`'s `dependencies`/`devDependencies` --not
+ * every transitive entry the lockfile carries. "Cheap, always available, no
+ * rerun needed" is the ruling's own bar; checking every transitive package
+ * on every execution is neither cheap nor targeted at what a developer
+ * actually declared, and the ruling's own example (`left-pad`) is a single
+ * named top-level package.
+ */
+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 this project could not be positively identified as a
+     * checkable Node target (no `package.json`, no lockfile, an unsupported
+     * lockfile shape, or malformed JSON in either file) -- "not applicable"
+     * rather than a guessed clean result. `mismatches` is always `[]` when
+     * `false`.
+     */
+    readonly applicable: boolean;
+    readonly mismatches: readonly DependencyVersionMismatch[];
+}
+/**
+ * Compares the lockfile-declared version of every direct dependency
+ * (`dependencies` + `devDependencies` in `package.json`) against the
+ * version actually installed under `node_modules`, for the Node project
+ * rooted at `cwd` -- the same `ServiceConfiguration.cwd` every collector in
+ * this repo already reads a spawned service's project root from.
+ *
+ * A dependency absent from the lockfile (a workspace/local-link
+ * dependency) or absent from `node_modules` entirely (never installed) is
+ * skipped, not reported -- both are real, different facts from a version
+ * mismatch, and reporting either as one would be a guess this function does
+ * not make.
+ */
+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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;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;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,SAAS,yBAAyB,EAAE,CAAC;CAC3D;AAuBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,4BAA4B,CA6CjF"}

package/dist/dependency-version-check.js

@@ -0,0 +1,121 @@
+/**
+ * `DEC-NEXT-fault-layer-empirical-confirmation.md`'s `dependency` mechanism:
+ * "declared (lockfile) version vs. resolved (installed) version at
+ * runtime. A mismatch is a structural fact, the same shape as
+ * `automation`'s `harnessFailure` flag — not inferred, recorded."
+ *
+ * ## Node-only, checked rather than assumed
+ *
+ * This repo's own multi-language stance (`CLAUDE.md`: "check what this
+ * repo's existing environment/dependency inspection code, if any, already
+ * assumes about target project types before assuming Node-only") was
+ * checked directly before writing this: `captureEnvironmentMetadata`
+ * (`environment-metadata.ts`, the closest existing thing) probes an
+ * arbitrary command's `--version` output and is genuinely language-agnostic,
+ * but nothing in this repo already reads a *lockfile* for any language --
+ * there was no existing dependency-inspection assumption to match, Node or
+ * otherwise. Node is the one target built here because it is the one the
+ * ruling's own example names (`"lockfile pins left-pad@1.3.0, resolved
+ * 1.2.0"`) and the one every fixture in this repo (`fixture-apps/
+ * broken-invoices-backend`) actually is. A future target (a Python
+ * `requirements.txt`/`pip freeze` pair, a Ruby `Gemfile.lock`) is a real,
+ * disclosed gap -- a second reader function beside this one, not a rewrite
+ * of it, the same "framework extractors are additive" shape
+ * `descry-core`'s own CLAUDE.md describes for its adapters.
+ *
+ * ## Only `lockfileVersion` 2/3's `packages` shape
+ *
+ * Confirmed against this repo's own `fixture-apps/broken-invoices-backend/
+ * package-lock.json` (`lockfileVersion: 3`) rather than assumed: modern npm
+ * writes a flat `packages` map keyed by the `node_modules/<name>` path the
+ * package would be installed at, each entry carrying the resolved
+ * `version` it was locked to -- exactly the "declared" half this function
+ * needs, with no separate resolution algorithm required, because the key
+ * itself already *is* the install path. `lockfileVersion` 1's older
+ * `dependencies` shape is not read here -- `applicable: false`, a
+ * disclosed gap, not a guess dressed up as a second code path.
+ *
+ * ## "Resolved" is a direct read, not `require.resolve`
+ *
+ * The lockfile key (`node_modules/<name>`) is already the exact path this
+ * function reads `package.json` from under the project root. This is
+ * deliberately not Node's own module-resolution algorithm (walking up
+ * successive `node_modules` directories) -- the lockfile key already
+ * encodes exactly where npm decided to place that install, including for a
+ * nested transitive dependency (`node_modules/a/node_modules/b`), and
+ * re-deriving that placement with a resolver would be solving a problem the
+ * lockfile already solved.
+ *
+ * ## Direct dependencies only
+ *
+ * Every name in `package.json`'s `dependencies`/`devDependencies` --not
+ * every transitive entry the lockfile carries. "Cheap, always available, no
+ * rerun needed" is the ruling's own bar; checking every transitive package
+ * on every execution is neither cheap nor targeted at what a developer
+ * actually declared, and the ruling's own example (`left-pad`) is a single
+ * named top-level package.
+ */
+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 the lockfile-declared version of every direct dependency
+ * (`dependencies` + `devDependencies` in `package.json`) against the
+ * version actually installed under `node_modules`, for the Node project
+ * rooted at `cwd` -- the same `ServiceConfiguration.cwd` every collector in
+ * this repo already reads a spawned service's project root from.
+ *
+ * A dependency absent from the lockfile (a workspace/local-link
+ * dependency) or absent from `node_modules` entirely (never installed) is
+ * skipped, not reported -- both are real, different facts from a version
+ * mismatch, and reporting either as one would be a guess this function does
+ * not make.
+ */
+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's `dependencies` shape, or a shape this reader does
+        // not recognise -- see this module's own 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAmCjC,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;;;;;;;;;;;;GAYG;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,wEAAwE;QACxE,iDAAiD;QACjD,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,16 @@
+/**
+ * Default environment applied to every spawned process, on top of whatever
+ * the caller passes explicitly.
+ *
+ * RUST_BACKTRACE is the concrete case this guards against (Agent 3's
+ * finding, plan §17): a Rust panic prints only a message and "run with
+ * RUST_BACKTRACE=1" without it. That is a collector-absence-masquerading-
+ * as-application-success case — the process didn't fail to crash, the
+ * runtime just failed to *see* how — so it belongs here rather than being
+ * left to each caller to remember.
+ *
+ * Only ever adds keys the caller didn't already set explicitly — never
+ * overrides a deliberate choice.
+ */
+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;;;;;;;;;;;;;GAaG;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,18 @@
+/**
+ * Default environment applied to every spawned process, on top of whatever
+ * the caller passes explicitly.
+ *
+ * RUST_BACKTRACE is the concrete case this guards against (Agent 3's
+ * finding, plan §17): a Rust panic prints only a message and "run with
+ * RUST_BACKTRACE=1" without it. That is a collector-absence-masquerading-
+ * as-application-success case — the process didn't fail to crash, the
+ * runtime just failed to *see* how — so it belongs here rather than being
+ * left to each caller to remember.
+ *
+ * Only ever adds keys the caller didn't already set explicitly — never
+ * overrides a deliberate choice.
+ */
+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;;;;;;;;;;;;;GAaG;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,23 @@
+/**
+ * §2's "commit is recorded; environment metadata is not captured" gap
+ * (RT-193): `Execution.commit` alone cannot reproduce a run -- the same
+ * commit under a different Node version, OS, or toolchain can behave
+ * differently, and nothing recorded which one actually ran.
+ * `captureEnvironmentMetadata` fills the missing half from the real host:
+ * OS platform, this controller process's own Node version (`process.version`
+ * -- always known, never probed), and the version of every distinct
+ * executable `configuration.services` actually invokes.
+ *
+ * The toolchain probe reuses `scripts/preflight.mjs`'s `interpreters()`
+ * shape rather than reinventing version detection: run the command with a
+ * version flag, read stdout+stderr combined (several of these tools --
+ * `java -version`, `javac -version`, `kotlinc -version` -- write to stderr
+ * only), keep the first line. It is not the same function, because
+ * `interpreters()` checks a fixed, hardcoded list of dev-environment
+ * toolchains against a specific expected-version regex per tool; this
+ * checks whatever `services[*].command` actually names, for any command,
+ * with no expected version to compare against -- a report, not a gate.
+ */
+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;;;;;;;;;;;;;;;;;;;GAmBG;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,CAqB9B"}

package/dist/environment-metadata.js

@@ -0,0 +1,80 @@
+/**
+ * §2's "commit is recorded; environment metadata is not captured" gap
+ * (RT-193): `Execution.commit` alone cannot reproduce a run -- the same
+ * commit under a different Node version, OS, or toolchain can behave
+ * differently, and nothing recorded which one actually ran.
+ * `captureEnvironmentMetadata` fills the missing half from the real host:
+ * OS platform, this controller process's own Node version (`process.version`
+ * -- always known, never probed), and the version of every distinct
+ * executable `configuration.services` actually invokes.
+ *
+ * The toolchain probe reuses `scripts/preflight.mjs`'s `interpreters()`
+ * shape rather than reinventing version detection: run the command with a
+ * version flag, read stdout+stderr combined (several of these tools --
+ * `java -version`, `javac -version`, `kotlinc -version` -- write to stderr
+ * only), keep the first line. It is not the same function, because
+ * `interpreters()` checks a fixed, hardcoded list of dev-environment
+ * toolchains against a specific expected-version regex per tool; this
+ * checks whatever `services[*].command` actually names, for any command,
+ * with no expected version to compare against -- a report, not a gate.
+ */
+import { execFile } from "node:child_process";
+import { platform } from "node:os";
+import { tokenizeCommand } from "./orchestration.js";
+/** Bounds a single version probe so a hung command can't stall run() -- same discipline RT-030 already applies to readiness probes, applied here to a probe this module owns instead of a caller's. */
+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 (`service.attach`) have no `command` -- nothing
+        // was launched by this runtime for it, so there is no toolchain to
+        // probe on its behalf.
+        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` then `-version` then `-v` -- the three flags
+ * `scripts/preflight.mjs`'s `interpreters()` needed across the toolchains
+ * this repo already runs (`java -version`, `mvn -v`). Returns the first
+ * line of whichever attempt exits 0, or `null` if none does -- an absent
+ * or non-version-reporting command is a disclosed gap in the map, not a
+ * thrown error and not an omitted key.
+ */
+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;;;;;;;;;;;;;;;;;;;GAmBG;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,uMAAuM;AACvM,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,uEAAuE;QACvE,mEAAmE;QACnE,uBAAuB;QACvB,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;;;;;;;GAOG;AACH,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,83 @@
+/**
+ * `DEC-NEXT-fault-layer-empirical-confirmation.md`'s `environment`
+ * mechanism: "declared/expected runner version (CI config) vs. observed
+ * runner version at execution." Same shape as `dependency-version-check.ts`'s
+ * comparison -- cheap, always available, no rerun needed.
+ *
+ * ## "Declared" is the project's own `.nvmrc`/`engines.node`, not a
+ * CI-workflow parser
+ *
+ * The ruling names "a CI config's pinned Node/language version" as one
+ * example of what "declared" can mean, not the only one -- its actual
+ * requirement is "whatever 'declared environment' already means elsewhere
+ * in this repo," checked directly rather than assumed (`environment-profile`
+ * turned out to mean something else entirely: DEC-270's safety level and
+ * credentials, not a version declaration). Nothing in this repo already
+ * parses a CI workflow file, and doing so first here would mean writing a
+ * YAML parser (or a regex sketch of one) for a signal that is, in every
+ * real Node project, already restated in `package.json` -- `.nvmrc` and
+ * `engines.node` are the actual, load-bearing declarations `nvm`/`npm`
+ * themselves read, checked directly against this repo's own root
+ * `package.json` (`engines: { node: ">=22.5" }`) and every fixture app
+ * under `fixture-apps/`, which all carry the same field. A future CI-file
+ * reader is a real, disclosed extension point, not a silent omission --
+ * this function's `declaredSource` is a closed union specifically so a
+ * third source can be added later without changing the shape callers
+ * already read.
+ *
+ * ## `satisfiesDeclaredNodeVersion`'s grammar is a real, narrower subset
+ *
+ * Supports `^x.y.z`, `~x.y.z`, `>=`/`<=`/`>`/`<` clauses, a bare version at
+ * any precision (`"20"`, `"20.11"`, `"20.11.5"`, each an x-range at that
+ * precision -- `"20"` means "any 20.x.y", matching what `actions/setup-node`
+ * itself does for a bare major), and space-separated AND clauses
+ * (`">=20.0.0 <21.0.0"`), npm's own shape for a bounded range. Does **not**
+ * support `||` (OR), hyphen ranges (`"1.2.3 - 2.3.4"`), prerelease/build
+ * tags, or the `x`/`*` wildcard tokens (`"20.x"`) -- an input using any of
+ * those parses to `null` ("cannot say") rather than a silently wrong
+ * true/false, the same "disclosed narrower scope, not a guess" pattern this
+ * repo already applies to `EnvironmentMetadata.toolchainVersions`' `null`
+ * entries.
+ */
+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 could be found at all (neither
+     * `.nvmrc` nor `package.json engines.node` present), or when the declared
+     * or observed value could not be parsed as a version -- "not applicable,"
+     * never a guessed clean result. `mismatch` is always `false` when this is
+     * `false`.
+     */
+    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 rooted at `cwd` and
+ * compares it against `observedVersion` (the real, already-known runtime
+ * value -- `process.version`, or `EnvironmentMetadata.nodeVersion`, the same
+ * "always known, never probed" value this repo already captures elsewhere;
+ * this function never probes for it itself).
+ *
+ * `.nvmrc` takes precedence over `package.json engines.node` when both are
+ * present -- `.nvmrc` names one exact intended version a developer actually
+ * runs locally; `engines.node` is more often a permissive range meant to
+ * describe compatibility rather than pin a single runtime. The narrower,
+ * more specific declaration wins, the same precedence
+ * `classifyFaultLayer` (`descry-core`) already applies between `dependency`
+ * and `environment` themselves ("the narrower, more specific structural
+ * fact... is checked first").
+ */
+export declare function checkEnvironmentVersion(cwd: string, observedVersion: string): EnvironmentVersionCheckResult;
+/**
+ * Whether `observedVersion` satisfies `declaredRange` under the grammar
+ * documented in this module's header. `null` means the comparison could not
+ * be made at all (either string used a construct this reader does not
+ * cover) -- distinct from `false`, which is a real, positive "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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAKH,eAAO,MAAM,wBAAwB,iDAAkD,CAAC;AACxF,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9E,MAAM,WAAW,6BAA6B;IAC5C;;;;;;OAMG;IACH,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;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,6BAA6B,CAiD3G;AAuGD;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,aAAa,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAU3G"}