@maverickcer/env-cap 0.7.5 → 0.7.7

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 (279) hide show
  1. package/ADOPTION.md +12 -12
  2. package/AGENTS.md +85 -120
  3. package/CHANGELOG.md +36 -0
  4. package/CODE_REVIEW.md +5 -5
  5. package/CONTRIBUTING.md +5 -5
  6. package/GUIDE.md +42 -24
  7. package/README.md +52 -34
  8. package/RELEASING.md +78 -64
  9. package/SECURITY.md +15 -15
  10. package/VERSIONING.md +16 -15
  11. package/benchmarks/READING-BENCHMARKS.md +101 -85
  12. package/benchmarks/README.md +12 -9
  13. package/benchmarks/WRITING-BENCHMARKS.md +89 -79
  14. package/benchmarks/performance-buildtime/BENCHMARKS.md +20 -20
  15. package/benchmarks/performance-runtime/BENCHMARKS.md +107 -107
  16. package/dist/.dts/_ipc/build-fs.d.ts +3 -3
  17. package/dist/.dts/_ipc/build-fs.d.ts.map +1 -1
  18. package/dist/.dts/_ipc/display-path.d.ts +1 -1
  19. package/dist/.dts/_ipc/glob.d.ts +3 -2
  20. package/dist/.dts/_ipc/glob.d.ts.map +1 -1
  21. package/dist/.dts/_ipc/no-node-fs.d.ts +2 -2
  22. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +16 -16
  23. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -1
  24. package/dist/.dts/_ipc/typescript.d.ts +4 -4
  25. package/dist/.dts/build/assemble-project.d.ts +14 -15
  26. package/dist/.dts/build/assemble-project.d.ts.map +1 -1
  27. package/dist/.dts/build/change-model.d.ts +14 -14
  28. package/dist/.dts/build/change-model.d.ts.map +1 -1
  29. package/dist/.dts/build/check-artifacts.d.ts +4 -4
  30. package/dist/.dts/build/check-artifacts.d.ts.map +1 -1
  31. package/dist/.dts/build/citation-verification.d.ts +13 -14
  32. package/dist/.dts/build/citation-verification.d.ts.map +1 -1
  33. package/dist/.dts/build/compatibility.d.ts +24 -24
  34. package/dist/.dts/build/compatibility.d.ts.map +1 -1
  35. package/dist/.dts/build/contract-model.d.ts +10 -10
  36. package/dist/.dts/build/contract-model.d.ts.map +1 -1
  37. package/dist/.dts/build/deep-equal.d.ts +2 -2
  38. package/dist/.dts/build/deep-freeze.d.ts +2 -2
  39. package/dist/.dts/build/dependency-graph.d.ts +48 -55
  40. package/dist/.dts/build/dependency-graph.d.ts.map +1 -1
  41. package/dist/.dts/build/dependency-model.d.ts +18 -18
  42. package/dist/.dts/build/dependency-model.d.ts.map +1 -1
  43. package/dist/.dts/build/discover.d.ts +11 -11
  44. package/dist/.dts/build/discover.d.ts.map +1 -1
  45. package/dist/.dts/build/docs.d.ts +34 -38
  46. package/dist/.dts/build/docs.d.ts.map +1 -1
  47. package/dist/.dts/build/env-example.d.ts +13 -13
  48. package/dist/.dts/build/env-example.d.ts.map +1 -1
  49. package/dist/.dts/build/errors.d.ts +8 -8
  50. package/dist/.dts/build/evidence-cache.d.ts +23 -23
  51. package/dist/.dts/build/evidence-cache.d.ts.map +1 -1
  52. package/dist/.dts/build/evidence-model.d.ts +3 -3
  53. package/dist/.dts/build/evidence-reference.d.ts +15 -15
  54. package/dist/.dts/build/evidence-reference.d.ts.map +1 -1
  55. package/dist/.dts/build/evidence-snapshot.d.ts +47 -53
  56. package/dist/.dts/build/evidence-snapshot.d.ts.map +1 -1
  57. package/dist/.dts/build/exclusive-group.d.ts +4 -4
  58. package/dist/.dts/build/exclusive-group.d.ts.map +1 -1
  59. package/dist/.dts/build/finding-model.d.ts +12 -12
  60. package/dist/.dts/build/finding-model.d.ts.map +1 -1
  61. package/dist/.dts/build/generate-documentation.d.ts +19 -19
  62. package/dist/.dts/build/generate-documentation.d.ts.map +1 -1
  63. package/dist/.dts/build/generate-env-artifacts.d.ts +43 -43
  64. package/dist/.dts/build/generate-env-artifacts.d.ts.map +1 -1
  65. package/dist/.dts/build/generate-evidence.d.ts +19 -19
  66. package/dist/.dts/build/generate-evidence.d.ts.map +1 -1
  67. package/dist/.dts/build/generate-manifest.d.ts +11 -12
  68. package/dist/.dts/build/generate-manifest.d.ts.map +1 -1
  69. package/dist/.dts/build/generate-usage.d.ts +23 -24
  70. package/dist/.dts/build/generate-usage.d.ts.map +1 -1
  71. package/dist/.dts/build/generated-banner.d.ts +5 -5
  72. package/dist/.dts/build/governance-fields.d.ts +7 -7
  73. package/dist/.dts/build/humanize-key.d.ts +1 -1
  74. package/dist/.dts/build/humanize-key.d.ts.map +1 -1
  75. package/dist/.dts/build/index.d.ts +20 -36
  76. package/dist/.dts/build/index.d.ts.map +1 -1
  77. package/dist/.dts/build/lifecycle-model.d.ts +87 -85
  78. package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
  79. package/dist/.dts/build/link.d.ts +38 -39
  80. package/dist/.dts/build/link.d.ts.map +1 -1
  81. package/dist/.dts/build/literal-eval.d.ts +2 -2
  82. package/dist/.dts/build/literal-eval.d.ts.map +1 -1
  83. package/dist/.dts/build/live-expirations.d.ts +14 -13
  84. package/dist/.dts/build/live-expirations.d.ts.map +1 -1
  85. package/dist/.dts/build/manifest.d.ts +6 -6
  86. package/dist/.dts/build/map-utils.d.ts +4 -4
  87. package/dist/.dts/build/merge-documentation.d.ts +9 -8
  88. package/dist/.dts/build/merge-documentation.d.ts.map +1 -1
  89. package/dist/.dts/build/ownership-model.d.ts +14 -15
  90. package/dist/.dts/build/ownership-model.d.ts.map +1 -1
  91. package/dist/.dts/build/parse.d.ts +20 -21
  92. package/dist/.dts/build/parse.d.ts.map +1 -1
  93. package/dist/.dts/build/reference-projections.d.ts +36 -38
  94. package/dist/.dts/build/reference-projections.d.ts.map +1 -1
  95. package/dist/.dts/build/resolution/resolve-import.d.ts +18 -14
  96. package/dist/.dts/build/resolution/resolve-import.d.ts.map +1 -1
  97. package/dist/.dts/build/resolution/resolve-package-schema.d.ts +26 -26
  98. package/dist/.dts/build/resolution/resolve-package-schema.d.ts.map +1 -1
  99. package/dist/.dts/build/resolution/resolve-within-root.d.ts +9 -9
  100. package/dist/.dts/build/sarif.d.ts +5 -5
  101. package/dist/.dts/build/sarif.d.ts.map +1 -1
  102. package/dist/.dts/build/scan-dependencies.d.ts +17 -16
  103. package/dist/.dts/build/scan-dependencies.d.ts.map +1 -1
  104. package/dist/.dts/build/sort-by-identity.d.ts +1 -1
  105. package/dist/.dts/build/source-position.d.ts +13 -13
  106. package/dist/.dts/build/tool-version.d.ts +1 -1
  107. package/dist/.dts/build/usage-report.d.ts +19 -19
  108. package/dist/.dts/build/usage-report.d.ts.map +1 -1
  109. package/dist/.dts/eslint-plugin/index.d.ts +16 -5
  110. package/dist/.dts/eslint-plugin/index.d.ts.map +1 -1
  111. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts +4 -4
  112. package/dist/.dts/evidence/define-projection.d.ts +15 -16
  113. package/dist/.dts/evidence/define-projection.d.ts.map +1 -1
  114. package/dist/.dts/evidence/index.d.ts +11 -15
  115. package/dist/.dts/evidence/index.d.ts.map +1 -1
  116. package/dist/.dts/helpers/index.d.ts +15 -18
  117. package/dist/.dts/helpers/index.d.ts.map +1 -1
  118. package/dist/.dts/helpers/validators.d.ts +2 -2
  119. package/dist/.dts/helpers/validators.d.ts.map +1 -1
  120. package/dist/.dts/node/index.d.ts +19 -0
  121. package/dist/.dts/node/index.d.ts.map +1 -1
  122. package/dist/.dts/runtime/create.d.ts +3 -3
  123. package/dist/.dts/runtime/document.d.ts +90 -99
  124. package/dist/.dts/runtime/document.d.ts.map +1 -1
  125. package/dist/.dts/runtime/errors.d.ts +5 -5
  126. package/dist/.dts/runtime/reset.d.ts +1 -1
  127. package/dist/.dts/runtime/types.d.ts +23 -24
  128. package/dist/.dts/runtime/types.d.ts.map +1 -1
  129. package/dist/.dts/runtime/validate.d.ts +1 -1
  130. package/dist/.dts7/_ipc/build-fs.d.ts +3 -3
  131. package/dist/.dts7/_ipc/build-fs.d.ts.map +1 -1
  132. package/dist/.dts7/_ipc/display-path.d.ts +1 -1
  133. package/dist/.dts7/_ipc/glob.d.ts +3 -2
  134. package/dist/.dts7/_ipc/glob.d.ts.map +1 -1
  135. package/dist/.dts7/_ipc/no-node-fs.d.ts +2 -2
  136. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +16 -16
  137. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -1
  138. package/dist/.dts7/_ipc/typescript.d.ts +4 -4
  139. package/dist/.dts7/build/assemble-project.d.ts +14 -15
  140. package/dist/.dts7/build/assemble-project.d.ts.map +1 -1
  141. package/dist/.dts7/build/change-model.d.ts +14 -14
  142. package/dist/.dts7/build/change-model.d.ts.map +1 -1
  143. package/dist/.dts7/build/check-artifacts.d.ts +4 -4
  144. package/dist/.dts7/build/check-artifacts.d.ts.map +1 -1
  145. package/dist/.dts7/build/citation-verification.d.ts +13 -14
  146. package/dist/.dts7/build/citation-verification.d.ts.map +1 -1
  147. package/dist/.dts7/build/compatibility.d.ts +24 -24
  148. package/dist/.dts7/build/compatibility.d.ts.map +1 -1
  149. package/dist/.dts7/build/contract-model.d.ts +10 -10
  150. package/dist/.dts7/build/contract-model.d.ts.map +1 -1
  151. package/dist/.dts7/build/deep-equal.d.ts +2 -2
  152. package/dist/.dts7/build/deep-freeze.d.ts +2 -2
  153. package/dist/.dts7/build/dependency-graph.d.ts +48 -55
  154. package/dist/.dts7/build/dependency-graph.d.ts.map +1 -1
  155. package/dist/.dts7/build/dependency-model.d.ts +18 -18
  156. package/dist/.dts7/build/dependency-model.d.ts.map +1 -1
  157. package/dist/.dts7/build/discover.d.ts +11 -11
  158. package/dist/.dts7/build/discover.d.ts.map +1 -1
  159. package/dist/.dts7/build/docs.d.ts +34 -38
  160. package/dist/.dts7/build/docs.d.ts.map +1 -1
  161. package/dist/.dts7/build/env-example.d.ts +13 -13
  162. package/dist/.dts7/build/env-example.d.ts.map +1 -1
  163. package/dist/.dts7/build/errors.d.ts +8 -8
  164. package/dist/.dts7/build/evidence-cache.d.ts +23 -23
  165. package/dist/.dts7/build/evidence-cache.d.ts.map +1 -1
  166. package/dist/.dts7/build/evidence-model.d.ts +3 -3
  167. package/dist/.dts7/build/evidence-reference.d.ts +15 -15
  168. package/dist/.dts7/build/evidence-reference.d.ts.map +1 -1
  169. package/dist/.dts7/build/evidence-snapshot.d.ts +47 -53
  170. package/dist/.dts7/build/evidence-snapshot.d.ts.map +1 -1
  171. package/dist/.dts7/build/exclusive-group.d.ts +4 -4
  172. package/dist/.dts7/build/exclusive-group.d.ts.map +1 -1
  173. package/dist/.dts7/build/finding-model.d.ts +12 -12
  174. package/dist/.dts7/build/finding-model.d.ts.map +1 -1
  175. package/dist/.dts7/build/generate-documentation.d.ts +19 -19
  176. package/dist/.dts7/build/generate-documentation.d.ts.map +1 -1
  177. package/dist/.dts7/build/generate-env-artifacts.d.ts +43 -43
  178. package/dist/.dts7/build/generate-env-artifacts.d.ts.map +1 -1
  179. package/dist/.dts7/build/generate-evidence.d.ts +19 -19
  180. package/dist/.dts7/build/generate-evidence.d.ts.map +1 -1
  181. package/dist/.dts7/build/generate-manifest.d.ts +11 -12
  182. package/dist/.dts7/build/generate-manifest.d.ts.map +1 -1
  183. package/dist/.dts7/build/generate-usage.d.ts +23 -24
  184. package/dist/.dts7/build/generate-usage.d.ts.map +1 -1
  185. package/dist/.dts7/build/generated-banner.d.ts +5 -5
  186. package/dist/.dts7/build/governance-fields.d.ts +7 -7
  187. package/dist/.dts7/build/humanize-key.d.ts +1 -1
  188. package/dist/.dts7/build/humanize-key.d.ts.map +1 -1
  189. package/dist/.dts7/build/index.d.ts +20 -36
  190. package/dist/.dts7/build/index.d.ts.map +1 -1
  191. package/dist/.dts7/build/lifecycle-model.d.ts +87 -85
  192. package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -1
  193. package/dist/.dts7/build/link.d.ts +38 -39
  194. package/dist/.dts7/build/link.d.ts.map +1 -1
  195. package/dist/.dts7/build/literal-eval.d.ts +2 -2
  196. package/dist/.dts7/build/literal-eval.d.ts.map +1 -1
  197. package/dist/.dts7/build/live-expirations.d.ts +14 -13
  198. package/dist/.dts7/build/live-expirations.d.ts.map +1 -1
  199. package/dist/.dts7/build/manifest.d.ts +6 -6
  200. package/dist/.dts7/build/map-utils.d.ts +4 -4
  201. package/dist/.dts7/build/merge-documentation.d.ts +9 -8
  202. package/dist/.dts7/build/merge-documentation.d.ts.map +1 -1
  203. package/dist/.dts7/build/ownership-model.d.ts +14 -15
  204. package/dist/.dts7/build/ownership-model.d.ts.map +1 -1
  205. package/dist/.dts7/build/parse.d.ts +20 -21
  206. package/dist/.dts7/build/parse.d.ts.map +1 -1
  207. package/dist/.dts7/build/reference-projections.d.ts +36 -38
  208. package/dist/.dts7/build/reference-projections.d.ts.map +1 -1
  209. package/dist/.dts7/build/resolution/resolve-import.d.ts +18 -14
  210. package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -1
  211. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts +26 -26
  212. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts.map +1 -1
  213. package/dist/.dts7/build/resolution/resolve-within-root.d.ts +9 -9
  214. package/dist/.dts7/build/sarif.d.ts +5 -5
  215. package/dist/.dts7/build/sarif.d.ts.map +1 -1
  216. package/dist/.dts7/build/scan-dependencies.d.ts +17 -16
  217. package/dist/.dts7/build/scan-dependencies.d.ts.map +1 -1
  218. package/dist/.dts7/build/sort-by-identity.d.ts +1 -1
  219. package/dist/.dts7/build/source-position.d.ts +13 -13
  220. package/dist/.dts7/build/tool-version.d.ts +1 -1
  221. package/dist/.dts7/build/usage-report.d.ts +19 -19
  222. package/dist/.dts7/build/usage-report.d.ts.map +1 -1
  223. package/dist/.dts7/eslint-plugin/index.d.ts +16 -5
  224. package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -1
  225. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +4 -4
  226. package/dist/.dts7/evidence/define-projection.d.ts +15 -16
  227. package/dist/.dts7/evidence/define-projection.d.ts.map +1 -1
  228. package/dist/.dts7/evidence/index.d.ts +11 -15
  229. package/dist/.dts7/evidence/index.d.ts.map +1 -1
  230. package/dist/.dts7/helpers/index.d.ts +15 -18
  231. package/dist/.dts7/helpers/index.d.ts.map +1 -1
  232. package/dist/.dts7/helpers/validators.d.ts +2 -2
  233. package/dist/.dts7/helpers/validators.d.ts.map +1 -1
  234. package/dist/.dts7/node/index.d.ts +19 -0
  235. package/dist/.dts7/node/index.d.ts.map +1 -1
  236. package/dist/.dts7/runtime/create.d.ts +3 -3
  237. package/dist/.dts7/runtime/document.d.ts +90 -99
  238. package/dist/.dts7/runtime/document.d.ts.map +1 -1
  239. package/dist/.dts7/runtime/errors.d.ts +5 -5
  240. package/dist/.dts7/runtime/reset.d.ts +1 -1
  241. package/dist/.dts7/runtime/types.d.ts +23 -24
  242. package/dist/.dts7/runtime/types.d.ts.map +1 -1
  243. package/dist/.dts7/runtime/validate.d.ts +1 -1
  244. package/dist/{build-DNAYWD2B.js → build-33O5SDTC.js} +37 -39
  245. package/dist/build-33O5SDTC.js.map +1 -0
  246. package/dist/build.cjs +36 -38
  247. package/dist/build.cjs.map +1 -1
  248. package/dist/build.js +36 -38
  249. package/dist/build.js.map +1 -1
  250. package/dist/{chunk-HAGMVMN5.js → chunk-4D67AQFY.js} +2 -2
  251. package/dist/cli/index.js +29 -28
  252. package/dist/cli/index.js.map +1 -1
  253. package/dist/eslint-plugin/index.cjs.map +1 -1
  254. package/dist/eslint-plugin/index.js.map +1 -1
  255. package/dist/evidence.cjs +1 -1
  256. package/dist/evidence.cjs.map +1 -1
  257. package/dist/evidence.js +1 -1
  258. package/dist/evidence.js.map +1 -1
  259. package/dist/helpers.cjs +4 -4
  260. package/dist/helpers.cjs.map +1 -1
  261. package/dist/helpers.js +4 -4
  262. package/dist/helpers.js.map +1 -1
  263. package/dist/index.cjs.map +1 -1
  264. package/dist/index.js.map +1 -1
  265. package/examples/README.md +1 -1
  266. package/package.json +20 -13
  267. package/schemas/contract-model.schema.json +7 -7
  268. package/schemas/env-cap-report.schema.json +88 -88
  269. package/skills/env-cap/SKILL.md +12 -13
  270. package/skills/env-cap/references/api.md +1 -1
  271. package/specs/architecture.md +145 -120
  272. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +9 -0
  273. package/specs/generated-artifacts.md +78 -70
  274. package/specs/migrations/README.md +6 -6
  275. package/specs/migrations/from-centralized-schema.md +1 -1
  276. package/specs/migrations/from-t3-env.md +9 -9
  277. package/PROMPT.md +0 -89
  278. package/dist/build-DNAYWD2B.js.map +0 -1
  279. /package/dist/{chunk-HAGMVMN5.js.map → chunk-4D67AQFY.js.map} +0 -0
@@ -1,11 +1,11 @@
1
1
  ---
2
2
  name: env-cap
3
- description: Load when a task creates or edits an env.schema.ts, calls createEnv, documentEnv or validateEnv, or generates env-cap manifests, docs or reports. Skip it for other environment work.
3
+ description: env-cap contracts. Load when a task writes or edits an env.schema.ts, calls createEnv, documentEnv or validateEnv, or generates the manifest, docs or reports from them.
4
4
  ---
5
5
 
6
6
  # @maverickcer/env-cap
7
7
 
8
- env-cap gives each capability (a feature, service or package) its own environment contract: declared once as a static schema, validated at startup, and documented and aggregated at build time.
8
+ Each feature declares the environment variables it needs and their format. Your app validates them all in one place at startup, fails fast on a bad value, and reports how they should be rotated before they expire. A feature is a folder or an installable package; the docs also call it a capability.
9
9
 
10
10
  Not for: loading .env files, storing secrets, or a single global env object.
11
11
 
@@ -49,17 +49,16 @@ From `examples/team-service/features/prisma/env.schema.ts`.
49
49
 
50
50
  ## Rules
51
51
 
52
- - Write each schema as a static literal in the module that owns it: schemas are parsed as source, never executed, so spreads, factories and re-exports are not understood.
53
- - Put `description`, `owner`, `expiresAt` and `category` in `documentEnv`. `createEnv` entries take `default`, `processor`, `validator`, `context`; its options `name` and `source: import.meta.url`.
54
- - Read a value through its owning contract (`paymentsEnv.STRIPE_KEY`). Never build a merged env object.
52
+ - Write each schema as a static literal in the module that owns it. Schemas are parsed, never executed, so spreads, factories and re-exports stay unresolved.
53
+ - Put `description`, `owner`, `expiresAt`, `refreshInstructions` and `category` in `documentEnv`. `createEnv` entries take `default`, `processor`, `validator`, `context`; its options `name` and `source: import.meta.url`.
54
+ - Read a value through its owning contract (`paymentsEnv.STRIPE_KEY`).
55
55
  - Call `validateEnv` once at startup, directly. Run the `generate*` functions only in a build script or CI.
56
- - Import only from package.json exports; `/build`, `/node` and `/eslint-plugin` are Node-only, never in browser code.
57
56
 
58
57
  ## Rely on
59
58
 
60
59
  - Reading a contract before `validateEnv` has run throws `EnvNotReadyError`.
61
- - Errors never contain values. Keep raw values out of your own processor and validator messages, and do not spread a contract.
62
- - `required: true` in `documentEnv` only documents a variable as required. Enforcement is the validator rejecting an empty value.
60
+ - Errors carry names, never values. Keep values out of your processor and validator messages; spreading a contract reads every value.
61
+ - `required: true` in `documentEnv` only documents a variable; the validator must reject an empty value.
63
62
  - `context` is a plain string your application activates, not a security boundary.
64
63
  - Two contracts may declare one variable name. Conflicting processor return types and exclusive-group violations are errors; differing processor or validator sources warn, and block under `onIncompatibility: "throw"`.
65
64
 
@@ -67,15 +66,15 @@ From `examples/team-service/features/prisma/env.schema.ts`.
67
66
 
68
67
  | Instead of | Do this |
69
68
  | --- | --- |
70
- | `createEnv({ ...base })`, or a schema built by a function | Declare the schema as a literal object in the module that owns it, then pass that one binding to `createEnv` and `documentEnv`. |
69
+ | `createEnv({ ...base })`, or a schema built by a function | One literal object, passed by the same binding to `createEnv` and `documentEnv`. |
71
70
  | `transformer` | `processor`. There is no alias. |
72
71
  | A live expiry fetched inside `env.schema.ts` | Keep a static `expiresAt`; pass `liveExpirationDates` to the generator. |
73
72
 
74
73
  ## Verify
75
74
 
76
- 1. Run the project's type check and tests.
77
- 2. After changing an `env.schema.ts`, update its `documentEnv()` entry and run `generate:env`. Commit generated files only if the project does; never hand-edit one.
78
- 3. Check imports against package.json exports.
75
+ 1. The project's type check and tests pass.
76
+ 2. After changing an `env.schema.ts`, update its `documentEnv()` entry and rerun the generate script (`generate:env`, or `node scripts/generate-env.mjs`); it exits 0. Change generated files only through that script, and commit them only if the project does.
77
+ 3. Check imports against package.json `exports`.
79
78
 
80
79
  Report any check you could not run, and any assumption you made.
81
80
 
@@ -88,4 +87,4 @@ Report any check you could not run, and any assumption you made.
88
87
 
89
88
  ## Authority
90
89
 
91
- Target `@maverickcer/env-cap@0.7.5`. The installed package's exports and type declarations are the API: do not invent exports, options or return values. Behaviour is established by its tests and examples. If this skill and the code disagree, say so rather than guessing.
90
+ Target `@maverickcer/env-cap@0.7.7`. The installed package's exports and type declarations are the API: use only what they declare. Its tests and examples establish its behaviour. When this skill and the code disagree, report the disagreement before acting on either.
@@ -1,6 +1,6 @@
1
1
  # @maverickcer/env-cap public API
2
2
 
3
- Every export a consumer can import, by entry point, for version 0.7.5. Generated from the package's committed API baselines; the type declarations in the installed package are the authority.
3
+ Every export a consumer can import, by entry point, for version 0.7.7. Generated from the package's committed API baselines; the type declarations in the installed package are the authority.
4
4
 
5
5
  ## `@maverickcer/env-cap`
6
6
 
@@ -1,16 +1,16 @@
1
1
  # Architecture
2
2
 
3
- Canonical current-state description of how `env-cap` is built and what guarantees its architecture
4
- provides. [`decisions/`](decisions/) holds the reasoning trail (the ADRs); this document is the
5
- destination those decisions arrived at, not the argument for them. For the product overview and
3
+ This is the canonical current-state description of how `env-cap` is built and which invariants its
4
+ architecture holds. [`decisions/`](decisions/) holds the reasoning trail (the ADRs). This document is
5
+ the destination those decisions arrived at, not the argument for them. For the product overview and
6
6
  integration guidance, see [README.md](../README.md) and [GUIDE.md](../GUIDE.md).
7
7
 
8
8
  - [Purpose](#purpose)
9
9
  - [Core invariants](#core-invariants)
10
10
  - [The entry points](#the-entry-points)
11
- - [`runtime/` — define, validate, cache, and expose environment values](#runtime--define-validate-cache-and-expose-environment-values)
12
- - [`build/` — discover, analyze, link, and generate artifacts](#build--discover-analyze-link-and-generate-artifacts)
13
- - [`helpers/` — optional processors and validators](#helpers--optional-processors-and-validators)
11
+ - [`runtime/`: define, validate, cache, and expose environment values](#runtime-define-validate-cache-and-expose-environment-values)
12
+ - [`build/`: discover, analyze, link, and generate artifacts](#build-discover-analyze-link-and-generate-artifacts)
13
+ - [`helpers/`: optional processors and validators](#helpers-optional-processors-and-validators)
14
14
  - [Documentation is parallel to runtime, not part of runtime state](#documentation-is-parallel-to-runtime-not-part-of-runtime-state)
15
15
  - [Data flow](#data-flow)
16
16
  - [Module layout](#module-layout)
@@ -20,11 +20,13 @@ integration guidance, see [README.md](../README.md) and [GUIDE.md](../GUIDE.md).
20
20
 
21
21
  `env-cap` treats an application's environment configuration as a set of capability-owned contracts,
22
22
  not as loose strings read off `process.env`. It does not perform secret storage, rotation, or
23
- retrieval itself: a capability declares the environment variables it depends on (`createEnv()`) and,
24
- optionally, the documentation metadata that describes them (`documentEnv()`); `env-cap` validates
25
- those declarations against real values at startup, and separately, at build time, discovers every
26
- declared contract across a project to produce manifests, documentation, ownership reports, and a
27
- canonical Evidence Model.
23
+ retrieval itself.
24
+
25
+ - A capability declares the environment variables it depends on (`createEnv()`). Optionally, it
26
+ also declares the documentation metadata that describes them (`documentEnv()`).
27
+ - At startup, `env-cap` validates those declarations against real values.
28
+ - Separately, at build time, it discovers every declared contract across a project. From those it
29
+ produces manifests, documentation, ownership reports, and a canonical Evidence Model.
28
30
 
29
31
  The architecture keeps two concerns from collapsing into one:
30
32
 
@@ -35,86 +37,95 @@ build-time -> project-wide discovery, documentation, and ownership visib
35
37
 
36
38
  The runtime never discovers anything; it only validates what a generated manifest already told it to
37
39
  expect. Build-time tooling never runs at startup; it only ever runs as an explicit CI/npm-script step.
38
- Neither one substitutes for the other, and a consumer can use either independently — validation with no
39
- generated artifacts at all (a hand-written manifest works), or discovery/documentation with no runtime
40
- validation (a project that only wants the ownership report).
40
+ Neither one substitutes for the other, and a consumer can use either independently:
41
+
42
+ - validation with no generated artifacts at all (a hand-written manifest works);
43
+ - discovery/documentation with no runtime validation (a project that only wants the ownership
44
+ report).
41
45
 
42
46
  ## Core invariants
43
47
 
44
- These are the guarantees the rest of the design exists to uphold. Each links to the section that
48
+ These are the invariants the rest of the design exists to uphold. Each links to the section that
45
49
  describes its mechanics.
46
50
 
47
51
  ### Runtime and build-time are strictly separate
48
52
 
49
53
  The runtime (`.`, `./helpers`) has zero npm dependencies, never touches the filesystem, never
50
54
  discovers files, and never imports Node-specific APIs. `./build` is Node-only developer tooling,
51
- never meant to reach a browser bundle — bundle-size and tree-shaking tests fail if runtime consumers
55
+ never meant to reach a browser bundle. Bundle-size and tree-shaking tests fail if runtime consumers
52
56
  accidentally receive build tooling or unrelated helper code. See
53
- [`runtime/`](#runtime--define-validate-cache-and-expose-environment-values) and
54
- [`build/`](#build--discover-analyze-link-and-generate-artifacts) below, and
57
+ [`runtime/`](#runtime-define-validate-cache-and-expose-environment-values) and
58
+ [`build/`](#build-discover-analyze-link-and-generate-artifacts) below, and
55
59
  [ADR 0004](decisions/0004-no-client-server-package-split.md).
56
60
 
57
61
  ### The build tool never imports or executes a schema file
58
62
 
59
- Discovery is AST analysis only (`build/parse.ts`, the TypeScript compiler API) — a schema file's
63
+ Discovery is AST analysis only (`build/parse.ts`, the TypeScript compiler API). A schema file's
60
64
  `createEnv()`/`documentEnv()` calls are read as syntax, never imported or run. This preserves the
61
- safety boundary required for CI environments and large monorepos: a malicious or merely broken schema
62
- file can't execute code just by being discovered. See
63
- [`build/`](#build--discover-analyze-link-and-generate-artifacts) and
65
+ safety boundary required for CI environments and large monorepos. A malicious or merely broken
66
+ schema file can't execute code by being discovered. See
67
+ [`build/`](#build-discover-analyze-link-and-generate-artifacts) and
64
68
  [ADR 0002](decisions/0002-static-analysis-never-execution.md).
65
69
 
66
70
  ### `./build` does not acquire filesystem access implicitly
67
71
 
68
- `./build` never imports `node:fs` itself — every public options object requires a caller-supplied
72
+ `./build` never imports `node:fs` itself. Every public options object requires a caller-supplied
69
73
  `BuildFileSystem` capability. The `env-cap` CLI (`src/cli/`) is the executable boundary that
70
- constructs the real `node:fs/promises` adapter and hands it in; a consumer running the generators
74
+ constructs the real `node:fs/promises` adapter and hands it in. A consumer running the generators
71
75
  from their own Node script imports that same adapter from `@maverickcer/env-cap/node`. This is the
72
- same discipline `repo-contract`'s ADR-0011 established for `spawn`/`env`: a library surface should
73
- not implicitly acquire a powerful ambient capability a caller did not explicitly provide. See
76
+ same discipline `repo-contract`'s ADR-0011 established for `spawn`/`env`. A library surface should
77
+ not implicitly acquire a privileged ambient capability that a caller did not explicitly provide. See
74
78
  [ADR 0040](decisions/0040-library-surfaces-do-not-acquire-node-fs.md).
75
79
 
76
80
  ### Documentation is inert at runtime
77
81
 
78
- `documentEnv()` is a source-level marker the build system discovers through AST analysis — it stores
82
+ `documentEnv()` is a source-level marker the build system discovers through AST analysis. It stores
79
83
  nothing in memory and adds no fields to a runtime contract. `createEnv()`'s runtime contracts and
80
- `documentEnv()`'s documentation metadata are separate concerns that happen to share a source file, not
81
- one pipeline. See
84
+ `documentEnv()`'s documentation metadata are separate concerns. They happen to share a source file,
85
+ but they are not one pipeline. See
82
86
  [Documentation is parallel to runtime, not part of runtime state](#documentation-is-parallel-to-runtime-not-part-of-runtime-state).
83
87
 
84
88
  ### Runtime contracts are self-redacting
85
89
 
86
- A contract's own `toString`/`console.log`/JSON representation never exposes resolved values —
90
+ A contract's own `toString`/`console.log`/JSON representation never exposes resolved values.
87
91
  `console.log(paymentsEnv)` prints `EnvContract("payments") { 1 variable(s) }`, never the underlying
88
92
  secret. Explicit property access (`paymentsEnv.STRIPE_KEY`) remains required to read a value. See
89
93
  [ADR 0006](decisions/0006-self-redacting-contracts.md) and [SECURITY.md](../SECURITY.md).
90
94
 
91
95
  ### Validation contexts gate participation, nothing else
92
96
 
93
- A variable with no `context` participates in every run; a variable with a `context` participates only
94
- when `activeContexts` contains that exact string — no prefix matching, no inference from ambient
95
- signals, no effect on `EnvContract`'s TypeScript shape, and no authorization/bundling meaning. See
96
- [Validation context invariants](#validation-context-invariants) below and
97
- [ADR 0022](decisions/0022-validation-contexts.md).
97
+ A variable with no `context` participates in every run. A variable with a `context` participates
98
+ only when `activeContexts` contains that exact string. There is no prefix matching and no inference
99
+ from ambient signals. A context has no effect on `EnvContract`'s TypeScript shape and carries no
100
+ authorization/bundling meaning. See [Validation context invariants](#validation-context-invariants)
101
+ below and [ADR 0022](decisions/0022-validation-contexts.md).
98
102
 
99
103
  ### Manifest compatibility is the one blocking category
100
104
 
101
- Of the three finding categories a generation run can produce — manifest compatibility/exclusive-group
102
- issues, documentation completeness, and dependency ownership — only the first ever blocks
103
- (`EnvProjectGenerationError`, nothing written). Documentation and ownership issues are heuristic
104
- signals with real, common false-positive causes; they're recorded as `Finding`s on the persisted
105
- Evidence Model instead, for a consumer to gate on explicitly if they want that enforced. See
106
- [Data flow](#data-flow) and [ADR 0038](decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md).
105
+ Only manifest compatibility/exclusive-group issues ever block a generation run
106
+ (`EnvProjectGenerationError`, nothing written). A run can produce three finding categories, and only
107
+ the first one blocks:
108
+
109
+ 1. manifest compatibility/exclusive-group issues;
110
+ 2. documentation completeness;
111
+ 3. dependency ownership.
112
+
113
+ Documentation and ownership issues are heuristic signals with real, common false-positive causes.
114
+ They're recorded as `Finding`s on the persisted Evidence Model instead. A consumer can gate on them
115
+ explicitly if they want that enforced. See [Data flow](#data-flow) and
116
+ [ADR 0038](decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md).
107
117
 
108
118
  ### The Evidence Model is always computed, independent of what's requested
109
119
 
110
- `computeArtifacts()` always builds the full `EvidenceModel` — the manifest/docs/ownership/`--evidence`
111
- flags only control which artifacts are additionally _written to disk_, never whether the underlying
112
- model is computed. See [Data flow](#data-flow) and
120
+ `computeArtifacts()` always builds the full `EvidenceModel`. The
121
+ manifest/docs/ownership/`--evidence` flags only control which artifacts are additionally _written
122
+ to disk_, never whether the underlying model is computed. See [Data flow](#data-flow) and
113
123
  [ADR 0038](decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md).
114
124
 
115
125
  ## The entry points
116
126
 
117
- `package.json` `exports` is the authoritative list (this section is the map of what each one is for, and TypeDoc generates the reference for each).
127
+ `package.json` `exports` is the authoritative list. This section is the map of what each one is
128
+ for, and TypeDoc generates the reference for each.
118
129
 
119
130
  ```text
120
131
 
@@ -135,40 +146,46 @@ include the implementation of the others.
135
146
  `build`, `eslint-plugin`, and `runtime` contain their own implementation with
136
147
  zero cross-folder dependency, including internal utilities.
137
148
  `globToRegExp()`, for example, is needed by both `build/discover.ts` and
138
- `eslint-plugin/no-raw-process-env.ts`; rather than living in a shared
139
- internal module both would depend on, each directory owns its own copy
140
- (`build/glob.ts`, `eslint-plugin/glob.ts` -- see ADR 0017's "Alternatives
141
- considered"). `helpers` and `evidence` each have exactly one cross-folder
142
- import, and both are structural, not incidental. `helpers`' `processors.ts`/
143
- `validators.ts` import `Processor`/`Validator` as types (erased at compile
144
- time) from `runtime/index.ts`, because a helper's whole job is producing a
145
- value that type-checks as the exact shape `createEnv()` expects -- that
146
- contract can't be expressed without referencing runtime's own type.
147
- `evidence/define-projection.ts` imports `EvidenceModel` as a type (also
148
- erased at compile time) from `build/evidence-model.ts`, for the same reason:
149
- a projector's whole job is a function _of_ that shape, which can't be named
150
- without referencing it -- see ADR 0031. Neither edge is an oversight: it's
151
- what lets any of these five directories move to its own repository
152
- independent of the others, with `helpers`/`evidence` simply gaining
153
- `env-cap`/`env-cap-build` as an ordinary
154
- dependency the way any package depending on another package's published
155
- types would.
149
+ `eslint-plugin/no-raw-process-env.ts`. Each directory owns its own copy
150
+ rather than sharing an internal module both would depend on:
151
+ `build/glob.ts` and `eslint-plugin/glob.ts` (see ADR 0017's "Alternatives
152
+ considered").
153
+
154
+ `helpers` and `evidence` each have exactly one cross-folder import, and both
155
+ are structural, not incidental:
156
+
157
+ - `helpers`' `processors.ts`/`validators.ts` import `Processor`/`Validator`
158
+ as types (erased at compile time) from `runtime/index.ts`. A helper's whole
159
+ job is producing a value that type-checks as the exact shape `createEnv()`
160
+ expects. That contract can't be expressed without referencing runtime's
161
+ own type.
162
+ - `evidence/define-projection.ts` imports `EvidenceModel` as a type (also
163
+ erased at compile time) from `build/evidence-model.ts`, for the same
164
+ reason. A projector's whole job is a function _of_ that shape, which can't
165
+ be named without referencing it (see ADR 0031).
166
+
167
+ Neither edge is an oversight. It's what lets any of these five directories
168
+ move to its own repository independent of the others. `helpers`/`evidence`
169
+ would gain `env-cap`/`env-cap-build` as an ordinary dependency, the way any
170
+ package depending on another package's published types would.
156
171
 
157
172
  `src/cli/` (the `env-cap` bin, not a `package.json#exports` subpath) has the
158
- same kind of real, intentional dependency on `build` -- it imports
173
+ same kind of real, intentional dependency on `build`. It imports
159
174
  `@maverickcer/env-cap/build`'s public surface (`src/build/index.ts`)
160
- directly, never an internal `build/*.ts` file, since generating artifacts
161
- from the command line requires the same engine `./build` exports. It is also
162
- the one place `node:fs` is acquired to build the concrete `BuildFileSystem`
163
- adapter `./build` requires (see [ADR 0040](decisions/0040-library-surfaces-do-not-acquire-node-fs.md)).
164
- A split-out `cli` package would simply declare `env-cap-build`
165
- as a normal npm dependency.
166
-
167
- This separation is enforced through automated checks. The tree-shaking tests
168
- and bundle-size checks fail if runtime consumers accidentally receive build
169
- tooling or unrelated helper code, and the `AmbientCapabilities` check
170
- fails if a published library entrypoint's packed output reaches for
171
- `node:fs` outside the CLI/`./node`/`./eslint-plugin` exceptions.
175
+ directly, never an internal `build/*.ts` file. Generating artifacts from the
176
+ command line requires the same engine `./build` exports. It is also the one
177
+ place `node:fs` is acquired to build the concrete `BuildFileSystem` adapter
178
+ `./build` requires (see [ADR 0040](decisions/0040-library-surfaces-do-not-acquire-node-fs.md)).
179
+ A split-out `cli` package would declare `env-cap-build` as a normal npm
180
+ dependency.
181
+
182
+ This separation is enforced through automated checks:
183
+
184
+ - The tree-shaking tests and bundle-size checks fail if runtime consumers
185
+ accidentally receive build tooling or unrelated helper code.
186
+ - The `AmbientCapabilities` check fails if a published library entrypoint's
187
+ packed output reaches for `node:fs` outside the
188
+ CLI/`./node`/`./eslint-plugin` exceptions.
172
189
 
173
190
  ```mermaid
174
191
  flowchart TB
@@ -213,13 +230,13 @@ flowchart TB
213
230
  ```
214
231
 
215
232
  `build`, `eslint-plugin`, and `runtime` have no edges between them above
216
- because none exist: each owns its own copy of shared internals (e.g.
233
+ because none exist. Each owns its own copy of shared internals (e.g.
217
234
  `glob.ts`) rather than importing from another entry point. `helpers`' and
218
235
  `evidence`'s single edges are both type-only and erased at compile time.
219
236
  This is what the tree-shaking and bundle-size tests in the previous
220
237
  paragraph actually verify.
221
238
 
222
- ## `runtime/` — define, validate, cache, and expose environment values
239
+ ## `runtime/`: define, validate, cache, and expose environment values
223
240
 
224
241
  The runtime package contains only the functionality required while an
225
242
  application is running.
@@ -236,19 +253,20 @@ environment values into validated application configuration.
236
253
 
237
254
  `createEnv()` (`runtime/create.ts`) creates a feature-owned environment
238
255
  contract. `validateEnv()` (`runtime/validate.ts`) executes every registered
239
- contract's processing pipeline against the provided environment values and
240
- caches successful results through `runtime/cache.ts`. Before running that
241
- pipeline for a given variable, it first checks whether the variable's
242
- `context` (if any) is in the run's `activeContexts` -- a variable that
243
- doesn't match is skipped entirely (no default/processor/validator runs) and
244
- stays in its not-ready state, exactly as if this run had never happened for
245
- it.
256
+ contract's processing pipeline against the provided environment values. It
257
+ caches successful results through `runtime/cache.ts`.
258
+
259
+ Before running that pipeline for a given variable, `validateEnv()` first
260
+ checks whether the variable's `context` (if any) is in the run's
261
+ `activeContexts`. A variable that doesn't match is skipped entirely (no
262
+ default/processor/validator runs). It stays in its not-ready state, exactly
263
+ as if this run had never happened for it.
246
264
 
247
265
  ### Validation context invariants
248
266
 
249
267
  A **validation context** is an application-defined string a variable may
250
268
  declare (`context`) and a validation run may activate (`activeContexts`).
251
- env-cap never interprets, detects, or infers these strings itself -- the
269
+ These strings are never interpreted, detected, or inferred by env-cap itself. The
252
270
  application always computes and passes `activeContexts` explicitly. The
253
271
  following invariants are load-bearing; none should be relaxed without a new
254
272
  ADR (see [ADR 0022](decisions/0022-validation-contexts.md)):
@@ -261,14 +279,14 @@ ADR (see [ADR 0022](decisions/0022-validation-contexts.md)):
261
279
  `activeContexts` from any ambient signal (`window`, `NODE_ENV`, a
262
280
  bundler `define`, etc.). The application always computes and passes it
263
281
  explicitly.
264
- 3. **Not cache identity.** `validateEnv()` stays one-shot per process: a
282
+ 3. **Not cache identity.** `validateEnv()` stays one-shot per process. A
265
283
  second call while already `"ready"` returns the first call's result
266
284
  outright, without inspecting the second call's `activeContexts`. There
267
285
  is no per-context cache dimension.
268
286
  4. **Not a type-level concept.** Validation contexts affect participation
269
- at `validateEnv()` time only -- they do not alter `EnvContract`'s
287
+ at `validateEnv()` time only. They do not alter `EnvContract`'s
270
288
  TypeScript shape, `InferEnvValue`, or any generated type. Every schema
271
- key remains a property of `EnvContract<S>` regardless of `context`; an
289
+ key remains a property of `EnvContract<S>` regardless of `context`. An
272
290
  out-of-context key throws `EnvNotReadyError` at access time, exactly
273
291
  like any value read before `validateEnv()` has run.
274
292
  5. **Not authorization.** Validation contexts are not an authentication,
@@ -276,7 +294,7 @@ ADR (see [ADR 0022](decisions/0022-validation-contexts.md)):
276
294
  participation only, never who may read a resolved value.
277
295
  6. **Not a bundling/security boundary.** Separate discovery/manifests (ADR 0004) remain the real mechanism for keeping server-only source out of
278
296
  client-bound code. `activeContexts` filtering happens after the schema
279
- is already wherever it's going to be -- it does not remove a variable's
297
+ is already wherever it's going to be. It does not remove a variable's
280
298
  definition (or its `default` value) from a bundle that imports it.
281
299
 
282
300
  `runtime/registry.ts` maintains the internal relationship between created
@@ -297,7 +315,7 @@ The runtime package intentionally:
297
315
  This keeps the runtime small, portable, and safe to include in browser,
298
316
  edge, serverless, and Node environments.
299
317
 
300
- ## `build/` — discover, analyze, link, and generate artifacts
318
+ ## `build/`: discover, analyze, link, and generate artifacts
301
319
 
302
320
  The build package contains developer tooling only. It exists to analyze a
303
321
  project's environment schemas and generate artifacts; it is not part of an
@@ -312,13 +330,15 @@ The build pipeline is responsible for:
312
330
  - detecting compatibility concerns (`build/compatibility.ts`,
313
331
  `build/exclusive-group.ts`)
314
332
  - scanning source files for variable access and deriving ownership findings
315
- (`build/scan-dependencies.ts`, `build/dependency-graph.ts`) -- a
316
- purely-syntactic, per-file walk that follows `contract.KEY` member access,
317
- object-destructuring, and one level of file-unique `const` aliasing, and
318
- records every shape it can't follow (a rest/nested/computed-key binding, a
319
- reassigned alias, the contract passed around as a value) as an explicit
320
- `escape` that widens a variable to `indeterminate`, never a false
321
- `unconsumed` (see ADR 0039)
333
+ (`build/scan-dependencies.ts`, `build/dependency-graph.ts`). This is a
334
+ purely-syntactic, per-file walk (see ADR 0039):
335
+ - it follows `contract.KEY` member access, object-destructuring, and one
336
+ level of file-unique `const` aliasing;
337
+ - it records every shape it can't follow (a rest/nested/computed-key
338
+ binding, a reassigned alias, the contract passed around as a value) as
339
+ an explicit `escape`;
340
+ - an `escape` widens a variable to `indeterminate`, never a false
341
+ `unconsumed`.
322
342
  - resolving live expiration overrides for documentation (`build/live-expirations.ts`)
323
343
  - generating output artifacts (`build/manifest.ts`, `build/docs.ts`,
324
344
  `build/env-example.ts`, `build/usage-report.ts`)
@@ -340,11 +360,11 @@ See
340
360
  for the reasoning behind AST analysis instead of dynamic imports.
341
361
 
342
362
  Every public options object in `build/index.ts` also carries a required
343
- `fs: BuildFileSystem` field -- `./build` itself never imports `node:fs`; see
363
+ `fs: BuildFileSystem` field. `./build` itself never imports `node:fs`; see
344
364
  [ADR 0040](decisions/0040-library-surfaces-do-not-acquire-node-fs.md) and the
345
365
  [Core invariants](#core-invariants) above.
346
366
 
347
- ## `helpers/` — optional processors and validators
367
+ ## `helpers/`: optional processors and validators
348
368
 
349
369
  The helpers package provides reusable implementations of the
350
370
  `Processor` and `Validator` function types defined by
@@ -472,26 +492,31 @@ flowchart TB
472
492
 
473
493
  `generateEnvArtifacts()` and `checkEnvArtifacts()` share one
474
494
  `computeArtifacts()` pass (discovery, parsing, linking, and blocking-finding
475
- checks) and only diverge at the last step: write, or compare-and-report (see
495
+ checks). They only diverge at the last step: write, or compare-and-report
496
+ (see
476
497
  [ADR 0011](decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md)
477
498
  and [ADR 0016](decisions/0016-check-mode-compute-before-compare-never-partial-write.md)).
499
+
478
500
  Manifest, docs, `.env.example`, the ownership report, and the persisted
479
501
  evidence artifact are each optional per `generateEnvArtifacts()`/
480
- `checkEnvArtifacts()` call (`manifest`/`docs`/`usage`/`evidence` options) and
481
- only appear above when requested. The `env-cap` CLI only exposes
482
- `--location`/`--evidence` of those four -- docs/`.env.example`/the ownership
483
- report have no CLI flag at all (ADR 0046: no verified runtime consumer, so
484
- generating them is application code calling `generateDocumentation()`/
485
- `generateUsageReport()` directly, not a CLI concern) -- except the
486
- `EvidenceModel` backing the persisted evidence artifact, which
487
- `computeArtifacts()` always builds regardless of whether `evidence`/
488
- `--evidence` was requested; that option only controls whether it's also
489
- written to disk (ADR 0038).
502
+ `checkEnvArtifacts()` call (`manifest`/`docs`/`usage`/`evidence` options).
503
+ They only appear above when requested.
504
+
505
+ - The `env-cap` CLI only exposes `--location`/`--evidence` of those four.
506
+ Docs/`.env.example`/the ownership report have no CLI flag at all (ADR
507
+ 0046). They have no verified runtime consumer, so generating them is
508
+ application code calling `generateDocumentation()`/
509
+ `generateUsageReport()` directly, not a CLI concern.
510
+ - The exception is the `EvidenceModel` backing the persisted evidence
511
+ artifact. `computeArtifacts()` always builds it, regardless of whether
512
+ `evidence`/`--evidence` was requested. That option only controls whether
513
+ it's also written to disk (ADR 0038).
514
+
490
515
  Manifest compatibility/exclusive-group issues are the one category that still
491
- blocks (`CHECKS`, ADR 0009) — a documentation or ownership issue never does;
492
- both are surfaced as `Finding`s on the evidence artifact instead, for a team
493
- to gate on in its own CI step if it wants that enforced. The GitHub Action wraps whichever mode a workflow invokes
494
- `env-cap --json` with.
516
+ blocks (`CHECKS`, ADR 0009). A documentation or ownership issue never does.
517
+ Both are surfaced as `Finding`s on the evidence artifact instead. A team can
518
+ gate on them in its own CI step if it wants that enforced. The GitHub Action
519
+ wraps whichever mode a workflow invokes `env-cap --json` with.
495
520
 
496
521
  ### 1. Author time
497
522
 
@@ -546,8 +571,8 @@ Validation happens once for the process lifetime.
546
571
  Each contract, per variable:
547
572
 
548
573
  1. checks whether the variable's `context` matches this run's
549
- `activeContexts` -- if not, skips every remaining step entirely and
550
- moves to the next variable (see "Validation context invariants" above)
574
+ `activeContexts`. If not, it skips every remaining step entirely and
575
+ moves to the next variable (see "Validation context invariants" above).
551
576
  2. reads its raw value
552
577
  3. applies its default
553
578
  4. runs its processor
@@ -586,10 +611,10 @@ contract.
586
611
 
587
612
  The `src/` tree mirrors the entry points described above:
588
613
  `runtime/`, `build/` (and `build/resolution/`), `helpers/`, `evidence/`,
589
- `eslint-plugin/`, plus `cli/` (the `env-cap` bin) and `node/` (the
590
- `@maverickcer/env-cap/node` executable-context entry that ships the CLI's
614
+ `eslint-plugin/`, plus `cli/` (the `env-cap` bin) and `node/`. `node/` is the
615
+ `@maverickcer/env-cap/node` executable-context entry. It ships the CLI's
591
616
  concrete `BuildFileSystem` adapter as a value for a consumer's own build
592
- script). See [The entry points](#the-entry-points) for the
617
+ script. See [The entry points](#the-entry-points) for the
593
618
  dependency rules between them.
594
619
 
595
620
  ## Architectural decisions
@@ -5,6 +5,15 @@
5
5
  Accepted. Implemented in `src/build/typescript.ts`. Supersedes the TypeScript 7 paragraph of
6
6
  [ADR 0047](0047-supported-toolchain-node-22-and-typescript-5-6.md).
7
7
 
8
+ ## Amendment
9
+
10
+ `bundleDependencies` lists `@typescript/typescript6` only. npm also bundles the dependencies of a
11
+ bundled package, so its `@typescript/old` payload still ships in the tarball. Listing
12
+ `@typescript/old` by name without a matching `dependencies` entry made npm add
13
+ `"@typescript/old": "*"` to the published manifest. The manifest then no longer matched the
14
+ tarball's package.json, which Socket reports as manifest confusion.
15
+ `test/build/typescript-bundled.test.ts` pins both facts.
16
+
8
17
  ## Context
9
18
 
10
19
  The build-time scanner (`src/build/parse.ts`, `scan-dependencies.ts`, `literal-eval.ts`,