@descryy/runtime-controller 0.2.1 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/LICENSE +6 -0
  2. package/dist/attach-fencing.d.ts +109 -0
  3. package/dist/attach-fencing.d.ts.map +1 -0
  4. package/dist/attach-fencing.js +215 -0
  5. package/dist/attach-fencing.js.map +1 -0
  6. package/dist/capability-registry.d.ts +0 -15
  7. package/dist/capability-registry.d.ts.map +1 -1
  8. package/dist/capability-registry.js +9 -19
  9. package/dist/capability-registry.js.map +1 -1
  10. package/dist/collector-version.d.ts +1 -8
  11. package/dist/collector-version.d.ts.map +1 -1
  12. package/dist/collector-version.js +1 -8
  13. package/dist/collector-version.js.map +1 -1
  14. package/dist/container-sandbox.d.ts +66 -150
  15. package/dist/container-sandbox.d.ts.map +1 -1
  16. package/dist/container-sandbox.js +62 -143
  17. package/dist/container-sandbox.js.map +1 -1
  18. package/dist/controller.d.ts +49 -106
  19. package/dist/controller.d.ts.map +1 -1
  20. package/dist/controller.js +65 -123
  21. package/dist/controller.js.map +1 -1
  22. package/dist/dependency-version-check.d.ts +19 -73
  23. package/dist/dependency-version-check.d.ts.map +1 -1
  24. package/dist/dependency-version-check.js +18 -67
  25. package/dist/dependency-version-check.js.map +1 -1
  26. package/dist/env.d.ts +4 -10
  27. package/dist/env.d.ts.map +1 -1
  28. package/dist/env.js +4 -10
  29. package/dist/env.js.map +1 -1
  30. package/dist/environment-metadata.d.ts +9 -17
  31. package/dist/environment-metadata.d.ts.map +1 -1
  32. package/dist/environment-metadata.js +12 -29
  33. package/dist/environment-metadata.js.map +1 -1
  34. package/dist/environment-version-check.d.ts +22 -65
  35. package/dist/environment-version-check.d.ts.map +1 -1
  36. package/dist/environment-version-check.js +24 -66
  37. package/dist/environment-version-check.js.map +1 -1
  38. package/dist/execution-safety.d.ts +54 -112
  39. package/dist/execution-safety.d.ts.map +1 -1
  40. package/dist/execution-safety.js +48 -102
  41. package/dist/execution-safety.js.map +1 -1
  42. package/dist/index.d.ts +2 -10
  43. package/dist/index.d.ts.map +1 -1
  44. package/dist/index.js +1 -0
  45. package/dist/index.js.map +1 -1
  46. package/dist/orchestration.d.ts +24 -39
  47. package/dist/orchestration.d.ts.map +1 -1
  48. package/dist/orchestration.js +39 -75
  49. package/dist/orchestration.js.map +1 -1
  50. package/dist/process-collector.d.ts +8 -22
  51. package/dist/process-collector.d.ts.map +1 -1
  52. package/dist/process-collector.js +23 -55
  53. package/dist/process-collector.js.map +1 -1
  54. package/dist/process-manager.d.ts +65 -80
  55. package/dist/process-manager.d.ts.map +1 -1
  56. package/dist/process-manager.js +80 -103
  57. package/dist/process-manager.js.map +1 -1
  58. package/dist/readiness.d.ts +28 -70
  59. package/dist/readiness.d.ts.map +1 -1
  60. package/dist/readiness.js +73 -95
  61. package/dist/readiness.js.map +1 -1
  62. package/dist/sandbox.d.ts +60 -105
  63. package/dist/sandbox.d.ts.map +1 -1
  64. package/dist/sandbox.js +78 -121
  65. package/dist/sandbox.js.map +1 -1
  66. package/package.json +8 -3
@@ -1,59 +1,18 @@
1
1
  /**
2
- * `DEC-NEXT-fault-layer-empirical-confirmation.md`'s `dependency` mechanism:
3
- * "declared (lockfile) version vs. resolved (installed) version at
4
- * runtime. A mismatch is a structural fact, the same shape as
5
- * `automation`'s `harnessFailure` flag — not inferred, recorded."
6
- *
7
- * ## Node-only, checked rather than assumed
8
- *
9
- * This repo's own multi-language stance (`CLAUDE.md`: "check what this
10
- * repo's existing environment/dependency inspection code, if any, already
11
- * assumes about target project types before assuming Node-only") was
12
- * checked directly before writing this: `captureEnvironmentMetadata`
13
- * (`environment-metadata.ts`, the closest existing thing) probes an
14
- * arbitrary command's `--version` output and is genuinely language-agnostic,
15
- * but nothing in this repo already reads a *lockfile* for any language --
16
- * there was no existing dependency-inspection assumption to match, Node or
17
- * otherwise. Node is the one target built here because it is the one the
18
- * ruling's own example names (`"lockfile pins left-pad@1.3.0, resolved
19
- * 1.2.0"`) and the one every fixture in this repo (`fixture-apps/
20
- * broken-invoices-backend`) actually is. A future target (a Python
21
- * `requirements.txt`/`pip freeze` pair, a Ruby `Gemfile.lock`) is a real,
22
- * disclosed gap -- a second reader function beside this one, not a rewrite
23
- * of it, the same "framework extractors are additive" shape
24
- * `descry-core`'s own CLAUDE.md describes for its adapters.
25
- *
26
- * ## Only `lockfileVersion` 2/3's `packages` shape
27
- *
28
- * Confirmed against this repo's own `fixture-apps/broken-invoices-backend/
29
- * package-lock.json` (`lockfileVersion: 3`) rather than assumed: modern npm
30
- * writes a flat `packages` map keyed by the `node_modules/<name>` path the
31
- * package would be installed at, each entry carrying the resolved
32
- * `version` it was locked to -- exactly the "declared" half this function
33
- * needs, with no separate resolution algorithm required, because the key
34
- * itself already *is* the install path. `lockfileVersion` 1's older
35
- * `dependencies` shape is not read here -- `applicable: false`, a
36
- * disclosed gap, not a guess dressed up as a second code path.
37
- *
38
- * ## "Resolved" is a direct read, not `require.resolve`
39
- *
40
- * The lockfile key (`node_modules/<name>`) is already the exact path this
41
- * function reads `package.json` from under the project root. This is
42
- * deliberately not Node's own module-resolution algorithm (walking up
43
- * successive `node_modules` directories) -- the lockfile key already
44
- * encodes exactly where npm decided to place that install, including for a
45
- * nested transitive dependency (`node_modules/a/node_modules/b`), and
46
- * re-deriving that placement with a resolver would be solving a problem the
47
- * lockfile already solved.
48
- *
49
- * ## Direct dependencies only
50
- *
51
- * Every name in `package.json`'s `dependencies`/`devDependencies` --not
52
- * every transitive entry the lockfile carries. "Cheap, always available, no
53
- * rerun needed" is the ruling's own bar; checking every transitive package
54
- * on every execution is neither cheap nor targeted at what a developer
55
- * actually declared, and the ruling's own example (`left-pad`) is a single
56
- * named top-level package.
2
+ * `DEC-NEXT-fault-layer-empirical-confirmation.md`'s `dependency` mechanism: declared
3
+ * (lockfile) vs resolved (installed) version — a structural fact, recorded not inferred.
4
+ *
5
+ * - Node-only, checked not assumed: no existing lockfile reader for any language to
6
+ * match. A Python/Ruby target is a real, disclosed gap — an additive second reader,
7
+ * not a rewrite.
8
+ * - Only `lockfileVersion` 2/3's flat `packages` map (keyed by `node_modules/<name>`,
9
+ * confirmed against `fixture-apps/broken-invoices-backend`). v1's `dependencies`
10
+ * shape is not read — `applicable: false`, disclosed gap.
11
+ * - "Resolved" is a direct read from the lockfile key's path, not Node module
12
+ * resolution — the key already encodes install location, including nested
13
+ * transitives (`node_modules/a/node_modules/b`).
14
+ * - Direct dependencies only (`dependencies`/`devDependencies`), not every transitive
15
+ * lockfile entry — matches the ruling's "cheap, always available" bar.
57
16
  */
58
17
  export interface DependencyVersionMismatch {
59
18
  readonly name: string;
@@ -63,28 +22,15 @@ export interface DependencyVersionMismatch {
63
22
  readonly resolvedVersion: string;
64
23
  }
65
24
  export interface DependencyVersionCheckResult {
66
- /**
67
- * `false` when this project could not be positively identified as a
68
- * checkable Node target (no `package.json`, no lockfile, an unsupported
69
- * lockfile shape, or malformed JSON in either file) -- "not applicable"
70
- * rather than a guessed clean result. `mismatches` is always `[]` when
71
- * `false`.
72
- */
25
+ /** `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`. */
73
26
  readonly applicable: boolean;
74
27
  readonly mismatches: readonly DependencyVersionMismatch[];
75
28
  }
76
29
  /**
77
- * Compares the lockfile-declared version of every direct dependency
78
- * (`dependencies` + `devDependencies` in `package.json`) against the
79
- * version actually installed under `node_modules`, for the Node project
80
- * rooted at `cwd` -- the same `ServiceConfiguration.cwd` every collector in
81
- * this repo already reads a spawned service's project root from.
82
- *
83
- * A dependency absent from the lockfile (a workspace/local-link
84
- * dependency) or absent from `node_modules` entirely (never installed) is
85
- * skipped, not reported -- both are real, different facts from a version
86
- * mismatch, and reporting either as one would be a guess this function does
87
- * not make.
30
+ * Compares lockfile-declared vs installed version for every direct dependency of the
31
+ * Node project rooted at `cwd`. A dependency missing from the lockfile (workspace/
32
+ * local-link) or from `node_modules` (never installed) is skipped, not reported —
33
+ * different facts from a mismatch, not guessed as one.
88
34
  */
89
35
  export declare function checkDependencyVersions(cwd: string): DependencyVersionCheckResult;
90
36
  //# sourceMappingURL=dependency-version-check.d.ts.map
@@ -1 +1 @@
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"}
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"}
@@ -1,59 +1,18 @@
1
1
  /**
2
- * `DEC-NEXT-fault-layer-empirical-confirmation.md`'s `dependency` mechanism:
3
- * "declared (lockfile) version vs. resolved (installed) version at
4
- * runtime. A mismatch is a structural fact, the same shape as
5
- * `automation`'s `harnessFailure` flag — not inferred, recorded."
2
+ * `DEC-NEXT-fault-layer-empirical-confirmation.md`'s `dependency` mechanism: declared
3
+ * (lockfile) vs resolved (installed) version — a structural fact, recorded not inferred.
6
4
  *
7
- * ## Node-only, checked rather than assumed
8
- *
9
- * This repo's own multi-language stance (`CLAUDE.md`: "check what this
10
- * repo's existing environment/dependency inspection code, if any, already
11
- * assumes about target project types before assuming Node-only") was
12
- * checked directly before writing this: `captureEnvironmentMetadata`
13
- * (`environment-metadata.ts`, the closest existing thing) probes an
14
- * arbitrary command's `--version` output and is genuinely language-agnostic,
15
- * but nothing in this repo already reads a *lockfile* for any language --
16
- * there was no existing dependency-inspection assumption to match, Node or
17
- * otherwise. Node is the one target built here because it is the one the
18
- * ruling's own example names (`"lockfile pins left-pad@1.3.0, resolved
19
- * 1.2.0"`) and the one every fixture in this repo (`fixture-apps/
20
- * broken-invoices-backend`) actually is. A future target (a Python
21
- * `requirements.txt`/`pip freeze` pair, a Ruby `Gemfile.lock`) is a real,
22
- * disclosed gap -- a second reader function beside this one, not a rewrite
23
- * of it, the same "framework extractors are additive" shape
24
- * `descry-core`'s own CLAUDE.md describes for its adapters.
25
- *
26
- * ## Only `lockfileVersion` 2/3's `packages` shape
27
- *
28
- * Confirmed against this repo's own `fixture-apps/broken-invoices-backend/
29
- * package-lock.json` (`lockfileVersion: 3`) rather than assumed: modern npm
30
- * writes a flat `packages` map keyed by the `node_modules/<name>` path the
31
- * package would be installed at, each entry carrying the resolved
32
- * `version` it was locked to -- exactly the "declared" half this function
33
- * needs, with no separate resolution algorithm required, because the key
34
- * itself already *is* the install path. `lockfileVersion` 1's older
35
- * `dependencies` shape is not read here -- `applicable: false`, a
36
- * disclosed gap, not a guess dressed up as a second code path.
37
- *
38
- * ## "Resolved" is a direct read, not `require.resolve`
39
- *
40
- * The lockfile key (`node_modules/<name>`) is already the exact path this
41
- * function reads `package.json` from under the project root. This is
42
- * deliberately not Node's own module-resolution algorithm (walking up
43
- * successive `node_modules` directories) -- the lockfile key already
44
- * encodes exactly where npm decided to place that install, including for a
45
- * nested transitive dependency (`node_modules/a/node_modules/b`), and
46
- * re-deriving that placement with a resolver would be solving a problem the
47
- * lockfile already solved.
48
- *
49
- * ## Direct dependencies only
50
- *
51
- * Every name in `package.json`'s `dependencies`/`devDependencies` --not
52
- * every transitive entry the lockfile carries. "Cheap, always available, no
53
- * rerun needed" is the ruling's own bar; checking every transitive package
54
- * on every execution is neither cheap nor targeted at what a developer
55
- * actually declared, and the ruling's own example (`left-pad`) is a single
56
- * named top-level package.
5
+ * - Node-only, checked not assumed: no existing lockfile reader for any language to
6
+ * match. A Python/Ruby target is a real, disclosed gap — an additive second reader,
7
+ * not a rewrite.
8
+ * - Only `lockfileVersion` 2/3's flat `packages` map (keyed by `node_modules/<name>`,
9
+ * confirmed against `fixture-apps/broken-invoices-backend`). v1's `dependencies`
10
+ * shape is not read — `applicable: false`, disclosed gap.
11
+ * - "Resolved" is a direct read from the lockfile key's path, not Node module
12
+ * resolution — the key already encodes install location, including nested
13
+ * transitives (`node_modules/a/node_modules/b`).
14
+ * - Direct dependencies only (`dependencies`/`devDependencies`), not every transitive
15
+ * lockfile entry — matches the ruling's "cheap, always available" bar.
57
16
  */
58
17
  import { existsSync, readFileSync } from "node:fs";
59
18
  import { join } from "node:path";
@@ -66,17 +25,10 @@ function readJsonFile(path) {
66
25
  }
67
26
  }
68
27
  /**
69
- * Compares the lockfile-declared version of every direct dependency
70
- * (`dependencies` + `devDependencies` in `package.json`) against the
71
- * version actually installed under `node_modules`, for the Node project
72
- * rooted at `cwd` -- the same `ServiceConfiguration.cwd` every collector in
73
- * this repo already reads a spawned service's project root from.
74
- *
75
- * A dependency absent from the lockfile (a workspace/local-link
76
- * dependency) or absent from `node_modules` entirely (never installed) is
77
- * skipped, not reported -- both are real, different facts from a version
78
- * mismatch, and reporting either as one would be a guess this function does
79
- * not make.
28
+ * Compares lockfile-declared vs installed version for every direct dependency of the
29
+ * Node project rooted at `cwd`. A dependency missing from the lockfile (workspace/
30
+ * local-link) or from `node_modules` (never installed) is skipped, not reported —
31
+ * different facts from a mismatch, not guessed as one.
80
32
  */
81
33
  export function checkDependencyVersions(cwd) {
82
34
  const packageJsonPath = join(cwd, "package.json");
@@ -91,8 +43,7 @@ export function checkDependencyVersions(cwd) {
91
43
  }
92
44
  const packages = lockfile.packages;
93
45
  if (packages === undefined || typeof packages !== "object") {
94
- // lockfileVersion 1's `dependencies` shape, or a shape this reader does
95
- // not recognise -- see this module's own header.
46
+ // lockfileVersion 1, or an unrecognized shape -- see header.
96
47
  return { applicable: false, mismatches: [] };
97
48
  }
98
49
  const declaredNames = new Set([
@@ -1 +1 @@
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"}
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 CHANGED
@@ -1,16 +1,10 @@
1
1
  /**
2
- * Default environment applied to every spawned process, on top of whatever
3
- * the caller passes explicitly.
2
+ * Default environment applied to every spawned process, on top of the caller's own.
4
3
  *
5
- * RUST_BACKTRACE is the concrete case this guards against (Agent 3's
6
- * finding, plan §17): a Rust panic prints only a message and "run with
7
- * RUST_BACKTRACE=1" without it. That is a collector-absence-masquerading-
8
- * as-application-success case — the process didn't fail to crash, the
9
- * runtime just failed to *see* how — so it belongs here rather than being
10
- * left to each caller to remember.
4
+ * RUST_BACKTRACE=1 (§17): without it a Rust panic prints only a message, hiding the
5
+ * trace — a collector-absence-masquerading-as-success case, not a caller-remembers-it case.
11
6
  *
12
- * Only ever adds keys the caller didn't already set explicitly — never
13
- * overrides a deliberate choice.
7
+ * Never overrides a key the caller already set.
14
8
  */
15
9
  export declare function withDefaultProcessEnv(env: Readonly<Record<string, string | undefined>>): Record<string, string | undefined>;
16
10
  //# sourceMappingURL=env.d.ts.map
package/dist/env.d.ts.map CHANGED
@@ -1 +1 @@
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"}
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 CHANGED
@@ -1,16 +1,10 @@
1
1
  /**
2
- * Default environment applied to every spawned process, on top of whatever
3
- * the caller passes explicitly.
2
+ * Default environment applied to every spawned process, on top of the caller's own.
4
3
  *
5
- * RUST_BACKTRACE is the concrete case this guards against (Agent 3's
6
- * finding, plan §17): a Rust panic prints only a message and "run with
7
- * RUST_BACKTRACE=1" without it. That is a collector-absence-masquerading-
8
- * as-application-success case — the process didn't fail to crash, the
9
- * runtime just failed to *see* how — so it belongs here rather than being
10
- * left to each caller to remember.
4
+ * RUST_BACKTRACE=1 (§17): without it a Rust panic prints only a message, hiding the
5
+ * trace — a collector-absence-masquerading-as-success case, not a caller-remembers-it case.
11
6
  *
12
- * Only ever adds keys the caller didn't already set explicitly — never
13
- * overrides a deliberate choice.
7
+ * Never overrides a key the caller already set.
14
8
  */
15
9
  export function withDefaultProcessEnv(env) {
16
10
  return { RUST_BACKTRACE: "1", ...env };
package/dist/env.js.map CHANGED
@@ -1 +1 @@
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"}
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"}
@@ -1,22 +1,14 @@
1
1
  /**
2
- * §2's "commit is recorded; environment metadata is not captured" gap
3
- * (RT-193): `Execution.commit` alone cannot reproduce a run -- the same
4
- * commit under a different Node version, OS, or toolchain can behave
5
- * differently, and nothing recorded which one actually ran.
6
- * `captureEnvironmentMetadata` fills the missing half from the real host:
7
- * OS platform, this controller process's own Node version (`process.version`
8
- * -- always known, never probed), and the version of every distinct
9
- * executable `configuration.services` actually invokes.
2
+ * §2/RT-193: `Execution.commit` alone can't reproduce a run — same commit, different
3
+ * Node/OS/toolchain can behave differently. Fills the gap from the real host: OS
4
+ * platform, this process's own `process.version`, and the version of every distinct
5
+ * executable `configuration.services` invokes.
10
6
  *
11
- * The toolchain probe reuses `scripts/preflight.mjs`'s `interpreters()`
12
- * shape rather than reinventing version detection: run the command with a
13
- * version flag, read stdout+stderr combined (several of these tools --
14
- * `java -version`, `javac -version`, `kotlinc -version` -- write to stderr
15
- * only), keep the first line. It is not the same function, because
16
- * `interpreters()` checks a fixed, hardcoded list of dev-environment
17
- * toolchains against a specific expected-version regex per tool; this
18
- * checks whatever `services[*].command` actually names, for any command,
19
- * with no expected version to compare against -- a report, not a gate.
7
+ * Toolchain probe mirrors `scripts/preflight.mjs`'s `interpreters()` (version flag,
8
+ * read stdout+stderr combined since some tools like `java -version` write to stderr
9
+ * only, keep first line) but isn't the same function: that one checks a fixed tool
10
+ * list against expected versions (a gate); this reports whatever `services[*].command`
11
+ * names, no expected version to compare against.
20
12
  */
21
13
  import type { EnvironmentMetadata, ServiceConfiguration } from "@descryy/runtime-contracts";
22
14
  export declare function captureEnvironmentMetadata(services: Readonly<Record<string, ServiceConfiguration>>): Promise<EnvironmentMetadata>;
@@ -1 +1 @@
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"}
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"}
@@ -1,34 +1,24 @@
1
1
  /**
2
- * §2's "commit is recorded; environment metadata is not captured" gap
3
- * (RT-193): `Execution.commit` alone cannot reproduce a run -- the same
4
- * commit under a different Node version, OS, or toolchain can behave
5
- * differently, and nothing recorded which one actually ran.
6
- * `captureEnvironmentMetadata` fills the missing half from the real host:
7
- * OS platform, this controller process's own Node version (`process.version`
8
- * -- always known, never probed), and the version of every distinct
9
- * executable `configuration.services` actually invokes.
2
+ * §2/RT-193: `Execution.commit` alone can't reproduce a run — same commit, different
3
+ * Node/OS/toolchain can behave differently. Fills the gap from the real host: OS
4
+ * platform, this process's own `process.version`, and the version of every distinct
5
+ * executable `configuration.services` invokes.
10
6
  *
11
- * The toolchain probe reuses `scripts/preflight.mjs`'s `interpreters()`
12
- * shape rather than reinventing version detection: run the command with a
13
- * version flag, read stdout+stderr combined (several of these tools --
14
- * `java -version`, `javac -version`, `kotlinc -version` -- write to stderr
15
- * only), keep the first line. It is not the same function, because
16
- * `interpreters()` checks a fixed, hardcoded list of dev-environment
17
- * toolchains against a specific expected-version regex per tool; this
18
- * checks whatever `services[*].command` actually names, for any command,
19
- * with no expected version to compare against -- a report, not a gate.
7
+ * Toolchain probe mirrors `scripts/preflight.mjs`'s `interpreters()` (version flag,
8
+ * read stdout+stderr combined since some tools like `java -version` write to stderr
9
+ * only, keep first line) but isn't the same function: that one checks a fixed tool
10
+ * list against expected versions (a gate); this reports whatever `services[*].command`
11
+ * names, no expected version to compare against.
20
12
  */
21
13
  import { execFile } from "node:child_process";
22
14
  import { platform } from "node:os";
23
15
  import { tokenizeCommand } from "./orchestration.js";
24
- /** 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. */
16
+ /** Bounds a version probe so a hung command can't stall run() — same discipline as RT-030's readiness probes. */
25
17
  const VERSION_PROBE_TIMEOUT_MS = 3000;
26
18
  export async function captureEnvironmentMetadata(services) {
27
19
  const commands = new Set();
28
20
  for (const service of Object.values(services)) {
29
- // Attach-mode services (`service.attach`) have no `command` -- nothing
30
- // was launched by this runtime for it, so there is no toolchain to
31
- // probe on its behalf.
21
+ // Attach-mode services have no `command` -- nothing to probe.
32
22
  if (service.command === undefined)
33
23
  continue;
34
24
  const tokenized = tokenizeCommand(service.command);
@@ -45,14 +35,7 @@ export async function captureEnvironmentMetadata(services) {
45
35
  toolchainVersions,
46
36
  };
47
37
  }
48
- /**
49
- * Tries `--version` then `-version` then `-v` -- the three flags
50
- * `scripts/preflight.mjs`'s `interpreters()` needed across the toolchains
51
- * this repo already runs (`java -version`, `mvn -v`). Returns the first
52
- * line of whichever attempt exits 0, or `null` if none does -- an absent
53
- * or non-version-reporting command is a disclosed gap in the map, not a
54
- * thrown error and not an omitted key.
55
- */
38
+ /** 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. */
56
39
  function probeVersion(command) {
57
40
  return tryFlags(command, ["--version", "-version", "-v"]);
58
41
  }
@@ -1 +1 @@
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"}
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"}
@@ -1,54 +1,23 @@
1
1
  /**
2
- * `DEC-NEXT-fault-layer-empirical-confirmation.md`'s `environment`
3
- * mechanism: "declared/expected runner version (CI config) vs. observed
4
- * runner version at execution." Same shape as `dependency-version-check.ts`'s
5
- * comparison -- cheap, always available, no rerun needed.
2
+ * `DEC-NEXT-fault-layer-empirical-confirmation.md`'s `environment` mechanism:
3
+ * declared/expected runner version vs observed, at execution. Same shape as
4
+ * `dependency-version-check.ts` -- cheap, always available, no rerun needed.
6
5
  *
7
- * ## "Declared" is the project's own `.nvmrc`/`engines.node`, not a
8
- * CI-workflow parser
9
- *
10
- * The ruling names "a CI config's pinned Node/language version" as one
11
- * example of what "declared" can mean, not the only one -- its actual
12
- * requirement is "whatever 'declared environment' already means elsewhere
13
- * in this repo," checked directly rather than assumed (`environment-profile`
14
- * turned out to mean something else entirely: DEC-270's safety level and
15
- * credentials, not a version declaration). Nothing in this repo already
16
- * parses a CI workflow file, and doing so first here would mean writing a
17
- * YAML parser (or a regex sketch of one) for a signal that is, in every
18
- * real Node project, already restated in `package.json` -- `.nvmrc` and
19
- * `engines.node` are the actual, load-bearing declarations `nvm`/`npm`
20
- * themselves read, checked directly against this repo's own root
21
- * `package.json` (`engines: { node: ">=22.5" }`) and every fixture app
22
- * under `fixture-apps/`, which all carry the same field. A future CI-file
23
- * reader is a real, disclosed extension point, not a silent omission --
24
- * this function's `declaredSource` is a closed union specifically so a
25
- * third source can be added later without changing the shape callers
26
- * already read.
27
- *
28
- * ## `satisfiesDeclaredNodeVersion`'s grammar is a real, narrower subset
29
- *
30
- * Supports `^x.y.z`, `~x.y.z`, `>=`/`<=`/`>`/`<` clauses, a bare version at
31
- * any precision (`"20"`, `"20.11"`, `"20.11.5"`, each an x-range at that
32
- * precision -- `"20"` means "any 20.x.y", matching what `actions/setup-node`
33
- * itself does for a bare major), and space-separated AND clauses
34
- * (`">=20.0.0 <21.0.0"`), npm's own shape for a bounded range. Does **not**
35
- * support `||` (OR), hyphen ranges (`"1.2.3 - 2.3.4"`), prerelease/build
36
- * tags, or the `x`/`*` wildcard tokens (`"20.x"`) -- an input using any of
37
- * those parses to `null` ("cannot say") rather than a silently wrong
38
- * true/false, the same "disclosed narrower scope, not a guess" pattern this
39
- * repo already applies to `EnvironmentMetadata.toolchainVersions`' `null`
40
- * entries.
6
+ * - "Declared" reads `.nvmrc`/`package.json engines.node`, not a CI-workflow parser
7
+ * -- nothing here already parses CI YAML, and these are the load-bearing
8
+ * declarations `nvm`/`npm` themselves read. A future CI-file reader is a
9
+ * disclosed extension point: `declaredSource` is a closed union so a third source
10
+ * can be added without changing callers' shape.
11
+ * - `satisfiesDeclaredNodeVersion`'s grammar supports `^x.y.z`, `~x.y.z`,
12
+ * `>=`/`<=`/`>`/`<`, a bare version at any precision (x-range at that precision,
13
+ * matching `actions/setup-node`), and space-separated AND clauses. Does NOT
14
+ * support `||`, hyphen ranges, prerelease/build tags, or `x`/`*` wildcards --
15
+ * those parse to `null` ("cannot say"), never a guessed true/false.
41
16
  */
42
17
  export declare const DECLARED_VERSION_SOURCES: readonly ["nvmrc", "package.json engines.node"];
43
18
  export type DeclaredVersionSource = (typeof DECLARED_VERSION_SOURCES)[number];
44
19
  export interface EnvironmentVersionCheckResult {
45
- /**
46
- * `false` when no declared version could be found at all (neither
47
- * `.nvmrc` nor `package.json engines.node` present), or when the declared
48
- * or observed value could not be parsed as a version -- "not applicable,"
49
- * never a guessed clean result. `mismatch` is always `false` when this is
50
- * `false`.
51
- */
20
+ /** `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. */
52
21
  readonly applicable: boolean;
53
22
  readonly mismatch: boolean;
54
23
  readonly declaredVersion: string | null;
@@ -56,28 +25,16 @@ export interface EnvironmentVersionCheckResult {
56
25
  readonly observedVersion: string;
57
26
  }
58
27
  /**
59
- * Reads the declared Node version for the project rooted at `cwd` and
60
- * compares it against `observedVersion` (the real, already-known runtime
61
- * value -- `process.version`, or `EnvironmentMetadata.nodeVersion`, the same
62
- * "always known, never probed" value this repo already captures elsewhere;
63
- * this function never probes for it itself).
28
+ * Reads the declared Node version for the project at `cwd`, compares against
29
+ * `observedVersion` (`process.version`/`EnvironmentMetadata.nodeVersion` -- never
30
+ * probed here).
64
31
  *
65
- * `.nvmrc` takes precedence over `package.json engines.node` when both are
66
- * present -- `.nvmrc` names one exact intended version a developer actually
67
- * runs locally; `engines.node` is more often a permissive range meant to
68
- * describe compatibility rather than pin a single runtime. The narrower,
69
- * more specific declaration wins, the same precedence
70
- * `classifyFaultLayer` (`descry-core`) already applies between `dependency`
71
- * and `environment` themselves ("the narrower, more specific structural
72
- * fact... is checked first").
32
+ * `.nvmrc` takes precedence over `engines.node` when both exist -- it names one
33
+ * exact version a developer runs locally, vs. a more often permissive compatibility
34
+ * range. Narrower/more specific wins, same precedence `classifyFaultLayer`
35
+ * (`descry-core`) applies between `dependency` and `environment`.
73
36
  */
74
37
  export declare function checkEnvironmentVersion(cwd: string, observedVersion: string): EnvironmentVersionCheckResult;
75
- /**
76
- * Whether `observedVersion` satisfies `declaredRange` under the grammar
77
- * documented in this module's header. `null` means the comparison could not
78
- * be made at all (either string used a construct this reader does not
79
- * cover) -- distinct from `false`, which is a real, positive "does not
80
- * satisfy" answer.
81
- */
38
+ /** 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. */
82
39
  export declare function satisfiesDeclaredNodeVersion(declaredRange: string, observedVersion: string): boolean | null;
83
40
  //# sourceMappingURL=environment-version-check.d.ts.map
@@ -1 +1 @@
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"}
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"}