@maverickcer/env-cap 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MaverickCER
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,279 @@
+# env-cap
+
+[![CI](https://img.shields.io/github/actions/workflow/status/maverickcer/env-cap/ci.yml?branch=main&label=CI)](https://github.com/maverickcer/env-cap/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/env-cap)](https://www.npmjs.com/package/env-cap)
+[![Bundle size](https://img.shields.io/endpoint?url=https://maverickcer.github.io/env-cap/size-badge.json)](specs/decisions/0008-gzip-size-budget.md)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ready-3178c6)](README.md#installation)
+
+**Define who owns your environment variables, why they exist, and where they are used.**
+
+`env-cap` turns environment configuration into capability-owned contracts you can version, review, validate, document, and query.
+
+It does not replace your existing configuration tools. `dotenv`, Zod, envalid, t3-env, secret managers, and plain `process.env` can stay exactly where they are. `env-cap` adds the layer they do not provide: **ownership, lifecycle, and project-wide evidence about whether declared configuration is actually consumed.**
+
+[See it run](#see-it-run) · [Quick Start](#quick-start) · [Why env-cap](#why-not-just-use-existing-tools)
+
+## See it run
+
+**Every environment variable has an owner, a reason to exist, and a lifecycle you can query.**
+
+A capability declares the environment it owns alongside the validation already needed at runtime:
+
+```ts
+// features/payments/env.schema.ts
+
+import { createEnv, documentEnv } from "@maverickcer/env-cap"
+
+const paymentsSchema = {
+  STRIPE_KEY: {
+    validator: (value: string) => value.startsWith("sk_") || 'Expected a key starting with "sk_".',
+  },
+}
+
+export const paymentsEnv = createEnv(paymentsSchema, { name: "payments" })
+
+documentEnv(paymentsSchema, {
+  owner: "payments-team",
+  variables: {
+    STRIPE_KEY: {
+      description: "Stripe secret key used to create charges and process refunds.",
+      owner: "payments-team",
+      expiresAt: "2027-01-01",
+      sensitivity: "secret",
+    },
+  },
+})
+```
+
+Run the build-time analysis against a real project:
+
+```text
+$ npx env-cap --location src/generated/env.manifest.ts --docs docs/ENVIRONMENT.md --ownership docs/OWNERSHIP.md
+
+Wrote manifest: src/generated/env.manifest.ts
+
+Discovered 1 contract(s).
+
+Wrote docs: docs/ENVIRONMENT.md
+
+1 variable(s)/contract(s) expiring soon or already expired:
+
+  - STRIPE_KEY in env: 2026-09-01 (expired 9d ago)
+
+Wrote dependency ownership report: docs/OWNERSHIP.md
+
+2 unconsumed owned variable(s):
+
+  - DATABASE_URL in app
+
+  - STRIPE_KEY in app
+```
+
+This is real CLI output from [`examples/application`](examples/application), not a mockup.
+
+The important part is what the analysis can establish:
+
+- `STRIPE_KEY` has an ownership and expiration record.
+- Its declared expiration has passed.
+- `DATABASE_URL` and `STRIPE_KEY` are declared as owned but are not consumed by the analyzed application.
+
+Those are facts about the application's configuration and dependencies, not merely the result of a value validator.
+
+## Why it exists
+
+A configuration value can be perfectly valid and still be a problem.
+
+A secret manager can store a credential securely. A validator can confirm that it has the expected shape. Neither answers:
+
+- Why does this variable exist?
+- Which capability actually depends on it?
+- Who owns it?
+- When should it be reviewed, rotated, or retired?
+- Is anything still consuming it?
+
+As applications grow, those answers tend to move into documentation, team knowledge, Slack messages, tickets, and conventions.
+
+That creates a different class of configuration failure:
+
+**the application can accept a variable that nobody owns, nobody uses, or nobody remembers to retire.**
+
+`env-cap` makes those decisions part of the code.
+
+A capability declares the environment it owns. A build-time pass turns those declarations into a project-wide manifest, documentation, ownership information, and evidence about what the codebase actually consumes.
+
+The distinction is simple:
+
+> **Validators answer whether a value is valid.
+> env-cap answers why the value exists, who owns it, and whether the application still uses it.**
+
+## Quick Start
+
+**Start with one capability.**
+
+```bash
+npm install @maverickcer/env-cap
+npx env-cap init
+```
+
+`init` scaffolds the same setup shown below: an `env.schema.ts` contract and a `scripts/generate-env.mjs` generator. It never overwrites existing files and never modifies `package.json`.
+
+`init` is Experimental. See [VERSIONING.md](VERSIONING.md).
+
+If you prefer to create the contract yourself, the minimum setup is:
+
+```ts
+// features/payments/env.schema.ts
+
+import { createEnv } from "@maverickcer/env-cap"
+
+export const paymentsEnv = createEnv(
+  {
+    STRIPE_KEY: {
+      validator: (value: string) =>
+        value.startsWith("sk_") || 'Expected a key starting with "sk_".',
+    },
+  },
+  { name: "payments" },
+)
+```
+
+Then validate the generated project manifest before using the capability:
+
+```ts
+// app.ts
+
+import { validateEnv } from "@maverickcer/env-cap"
+
+import { manifest } from "./generated/env.manifest"
+import { paymentsEnv } from "./features/payments/env.schema"
+
+await validateEnv({
+  manifest,
+  values: process.env,
+})
+
+paymentsEnv.STRIPE_KEY
+```
+
+The normal flow is:
+
+```text
+declare → generate → validate → consume
+```
+
+`generateEnvManifest()` produces the project-wide manifest. Runtime validation uses that manifest against the environment values supplied by the application.
+
+See the [Guide's Core workflow](GUIDE.md#core-workflow) for the complete generate/validate cycle.
+
+Node.js `>=18`. TypeScript 5+ is only required for build-time manifest generation; the runtime works in plain JavaScript. See the [runtime support matrix](GUIDE.md#runtime-support-matrix) for Node, browser bundles, edge runtimes, Bun, and Deno.
+
+## Why not just use existing tools?
+
+`env-cap` is deliberately additive.
+
+| Tool                   | What it solves                                          | What remains unanswered                                                             |
+| ---------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `dotenv`               | Loads values from a `.env` file                         | Who owns the value, why it exists, whether it is still used, when it expires        |
+| Zod / envalid / t3-env | Validates value shape and types                         | Whether the variable is still needed, who owns it, or what capability depends on it |
+| Secret manager         | Stores and manages secrets                              | Which capability in the codebase actually consumes the secret                       |
+| `env-cap`              | Defines ownership, lifecycle, and consumption contracts | Does not replace loading, secret storage, or application-specific validation        |
+
+**You keep your existing tools.**
+
+Use `env-cap` with your existing validator or processor, or use its lightweight helpers when a dedicated validation library is unnecessary. What env-cap adds is the layer around the value: ownership, lifecycle, and project-wide evidence about whether declared configuration is actually consumed.
+
+You do not have to migrate away from an existing configuration library to adopt env-cap. The [migration guides](specs/migrations/) document the adoption path for `dotenv`, Zod, envalid, and t3-env, including cases where switching is unnecessary.
+
+## From one schema to a whole organization
+
+```text
+one schema, one team
+      |  ownership boundaries start to matter
+capability-owned schemas, one per feature
+      |  share it
+reusable package contracts
+      |  scale it
+organization-wide configuration ownership
+```
+
+A capability contract records what a variable is for, who owns it, how sensitive it is, when it expires, and whether the codebase still consumes it. Start with a single centralized schema and move toward capability- or package-owned contracts only as ownership boundaries start to matter — `generateEnvManifest()` produces one project-wide manifest regardless of how many contracts contribute to it, so validation, documentation, and ownership reporting never depend on how the schema is organized.
+
+The [`examples/`](examples/) directory has three runnable stages of that model — [`examples/application`](examples/application), [`examples/team-service`](examples/team-service), and [`examples/enterprise-platform`](examples/enterprise-platform) — and the [Guide](GUIDE.md#capability-owned-contracts) covers the full walkthrough.
+
+## You probably don't need it when
+
+A validation library or `dotenv` may be enough when:
+
+- the application is small;
+- one team owns every configuration decision;
+- there are only a few environment variables;
+- variables rarely change;
+- ownership and lifecycle are already obvious;
+- you do not need project-wide evidence about configuration usage.
+
+`env-cap` becomes more useful when configuration starts crossing capability, team, package, or organizational boundaries.
+
+## Works with automated contributors
+
+AI coding agents, CI bots, and release automation can consume the same manifests and evidence artifacts as human contributors.
+
+A structured finding such as:
+
+```text
+payments owns STRIPE_KEY
+STRIPE_KEY is declared but unconsumed
+```
+
+gives automation a concrete fact to investigate.
+
+That is more useful than a generic failure such as:
+
+```text
+configuration check failed
+```
+
+The repository can therefore use the same configuration contract to guide both human and automated changes.
+
+See the [AI Integration Prompt](./PROMPT.md) for a repository-aware review workflow.
+
+## Status
+
+`env-cap` is currently in `0.x`.
+
+Per [VERSIONING.md](VERSIONING.md), a minor release may include a breaking change to a Stable-tier API before 1.0. Pin according to your upgrade policy.
+
+The architecture is considered stable; APIs may continue to evolve based on production usage.
+
+## Learn more
+
+- **[Guide](GUIDE.md)** — capability-owned contracts, the complete generate/validate workflow, validation contexts, reusable packages, path aliases, CLI, GitHub Action, ESLint plugin, and performance characteristics.
+
+- **[Security](SECURITY.md)** — threat model, secret-handling boundaries, and application responsibilities.
+
+- **[Adoption guide](ADOPTION.md)** — decision-maker summary covering security posture, bundle size, and versioning/LTS considerations.
+
+- **[Migration guides](specs/migrations/)** — adoption alongside `dotenv`, Zod, envalid, or t3-env.
+
+- **[API reference](https://maverickcer.github.io/env-cap/api/)** — every exported symbol, generated from source.
+
+- **[Architecture](specs/architecture.md)** and **[ADRs](specs/decisions/)** — why env-cap is designed this way.
+
+- **[Examples](examples/)** — runnable application, team-service, and enterprise-platform examples.
+
+## If this is useful
+
+If capability-owned configuration matches how you think about environment variables, try env-cap against one real schema.
+
+If it does not fit your application's configuration model, [open an issue](https://github.com/MaverickCER/env-cap/issues) and explain why.
+
+## Contributing
+
+Start with [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, the change workflow, ADRs, and changeset-based versioning.
+
+[CODE_REVIEW.md](CODE_REVIEW.md) covers the reviewer-side process.
+
+Maintainers can see [RELEASING.md](RELEASING.md) for the release process.
+
+## License
+
+MIT

package/dist/.dts/build/assemble-project.d.ts

@@ -0,0 +1,47 @@
+import type { LinkResult } from "./link.js";
+import type { ParseWarning } from "./parse.js";
+import type { BuildFileSystem } from "./types.js";
+import type { ImportResolutionContext } from "./resolution/resolve-import.js";
+import type { PackageOrigin } from "./resolution/resolve-package-schema.js";
+/** Options for {@link assembleProject}. */
+export interface AssembleProjectOptions {
+    /** The filesystem capability -- `./build` never imports `node:fs` (ADR 0040). */
+    readonly fs: BuildFileSystem;
+    readonly root: string;
+    readonly include: readonly string[];
+    readonly exclude: readonly string[];
+    readonly packages: readonly string[];
+    readonly tsconfig: string | false | undefined;
+}
+/**
+ * Everything downstream model-building and artifact-rendering needs from one
+ * discovery+link pass: the linked contract graph, the import-resolution
+ * context every later resolution call (`computeScanSurface()`,
+ * `buildDependencyModel()`, ...) must reuse to agree with `linkResult`, and a
+ * shared file-read cache so a file matched by more than one later pass'
+ * glob (e.g. a schema file also matched by the usage pass' broader
+ * `SCAN_INCLUDE`) is only ever read from disk once.
+ */
+export interface AssembledProject {
+    readonly root: string;
+    readonly readFileCached: (filePath: string) => Promise<string>;
+    readonly linkResult: LinkResult;
+    readonly context: ImportResolutionContext;
+    /** Keyed by resolved file path -- see `resolveAllowlistedPackages()`. */
+    readonly origins: ReadonlyMap<string, PackageOrigin>;
+    readonly packageWarnings: readonly ParseWarning[];
+    readonly tsconfigWarnings: readonly ParseWarning[];
+}
+/**
+ * The one shared discovery+link pass every orchestrator needs -- local +
+ * allow-listed-package schema discovery, tsconfig path-alias resolution, and
+ * cross-file linking, exactly once. Extracted from what `computeArtifacts()`
+ * (`generate-env-artifacts.ts`) and `generateEvidenceModel()`
+ * (`generate-evidence.ts`) each used to run independently, so the two
+ * orchestrators can never silently drift into scanning the same source tree
+ * twice -- the same "shared discovery, computed once" principle ADR 0011
+ * already established for manifest/docs/usage, now shared with evidence
+ * assembly too.
+ */
+export declare function assembleProject(options: AssembleProjectOptions): Promise<AssembledProject>;
+//# sourceMappingURL=assemble-project.d.ts.map

package/dist/.dts/build/assemble-project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assemble-project.d.ts","sourceRoot":"","sources":["../../../src/build/assemble-project.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AACjD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAA;AAK7E,OAAO,KAAK,EACV,aAAa,EAEd,MAAM,wCAAwC,CAAA;AAM/C,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACrC,iFAAiF;IACjF,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;CAC9C;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAC9D,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;IAC/B,QAAQ,CAAC,OAAO,EAAE,uBAAuB,CAAA;IACzC,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IACpD,QAAQ,CAAC,eAAe,EAAE,SAAS,YAAY,EAAE,CAAA;IACjD,QAAQ,CAAC,gBAAgB,EAAE,SAAS,YAAY,EAAE,CAAA;CACnD;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA2ChG"}

package/dist/.dts/build/change-model.d.ts

@@ -0,0 +1,62 @@
+import type { DiscoveredContract } from "./link.js";
+import type { ManifestChangeReport } from "./evidence-snapshot.js";
+/**
+ * The sixth of env-cap's seven canonical fact models (ADR 0024) -- what
+ * changed since the last persisted evidence snapshot (ADR 0038; previously
+ * a manifest-scoped snapshot, ADR 0021). See ADR 0030 (base shape) and ADR
+ * 0029 (the `renamedFrom` field this file's rename correlation is gated
+ * on).
+ *
+ * @remarks
+ * Wraps `ManifestChangeReport` (`evidence-snapshot.ts`) rather than
+ * replacing it -- this model exists to give the change report a versioned,
+ * model-namespaced shape Evidence Model can assemble against, alongside the
+ * other six models. Empty (no adds/removes/updates) whenever no previous
+ * evidence snapshot location was configured for this run -- there is
+ * nothing to diff against, which is a genuinely different state from a
+ * first-ever run *with* tracking configured (where everything reads as
+ * added).
+ */
+/** Bump only when a reader could misinterpret the new shape -- same discipline every other canonical model's `schemaVersion` follows. */
+export declare const CHANGE_MODEL_SCHEMA_VERSION = 1;
+/** One `addedVariables`/`removedVariables` pair in `manifest`, correlated into a single rename via the current declaration's `renamedFrom` field (ADR 0029). */
+export interface RenamedVariable {
+    /** The owning contract's identity (`${file}#${exportName}`) -- a rename never crosses contracts. */
+    readonly contractIdentity: string;
+    readonly file: string;
+    readonly exportName: string;
+    readonly contractName: string;
+    /** The variable's key before the rename -- matches a `manifest.removedVariables` entry. */
+    readonly previousKey: string;
+    /** The variable's key after the rename -- matches a `manifest.addedVariables` entry. */
+    readonly currentKey: string;
+}
+export interface ChangeModel {
+    readonly schemaVersion: typeof CHANGE_MODEL_SCHEMA_VERSION;
+    /** The existing manifest change report, unmodified -- see ADR 0021. `addedVariables`/`removedVariables` still list a correlated rename's two halves separately; `renamedVariables` below is an additive, separately-computed view, not a filter over this field. */
+    readonly manifest: ManifestChangeReport;
+    /**
+     * Every `addedVariables`/`removedVariables` pair this run's currently
+     * declared `renamedFrom` values correlate into a single rename, sorted by
+     * contract identity then current key.
+     *
+     * @remarks
+     * Only ever populated from an *authored* `renamedFrom` -- never guessed
+     * from name similarity (ADR 0010's "provable, not heuristic" ethos).
+     * Variable-level only: Lifecycle Model deliberately has no contract-level
+     * `renamedFrom` (ADR 0029), so there is no `renamedContracts` -- a
+     * contract-level rename has no field to correlate from.
+     */
+    readonly renamedVariables: readonly RenamedVariable[];
+}
+/**
+ * Wraps an already-computed `ManifestChangeReport` (e.g.
+ * `generateEnvArtifacts()`'s internal `evidenceChanges.report`) in the Change Model's versioned
+ * shape, and correlates renames using the current run's `renamedFrom`
+ * declarations. `currentContracts` should be the same contracts the
+ * manifest was generated from (active contracts only, matching
+ * `renderManifest()`'s own scope -- same as every other input to this
+ * report family).
+ */
+export declare function buildChangeModel(manifest: ManifestChangeReport, currentContracts: readonly DiscoveredContract[], root: string): ChangeModel;
+//# sourceMappingURL=change-model.d.ts.map

package/dist/.dts/build/change-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-model.d.ts","sourceRoot":"","sources":["../../../src/build/change-model.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,KAAK,EAAE,oBAAoB,EAAuB,MAAM,wBAAwB,CAAA;AAEvF;;;;;;;;;;;;;;;;GAgBG;AAEH,yIAAyI;AACzI,eAAO,MAAM,2BAA2B,IAAI,CAAA;AAE5C,gKAAgK;AAChK,MAAM,WAAW,eAAe;IAC9B,oGAAoG;IACpG,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,2FAA2F;IAC3F,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,wFAAwF;IACxF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,aAAa,EAAE,OAAO,2BAA2B,CAAA;IAC1D,oQAAoQ;IACpQ,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAA;IACvC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,gBAAgB,EAAE,SAAS,eAAe,EAAE,CAAA;CACtD;AAqBD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,oBAAoB,EAC9B,gBAAgB,EAAE,SAAS,kBAAkB,EAAE,EAC/C,IAAI,EAAE,MAAM,GACX,WAAW,CAkDb"}

package/dist/.dts/build/check-artifacts.d.ts

@@ -0,0 +1,48 @@
+import type { GenerateEnvArtifactsOptions } from "./generate-env-artifacts.js";
+/**
+ * `--check` / drift-guard support: computes every requested artifact exactly
+ * as a real run would, but never writes to any of the four real target
+ * paths. See ADR 0016.
+ */
+/** One artifact's drift status, as found by {@link checkEnvArtifacts}. */
+export interface ArtifactCheckFinding {
+    /** Which generated artifact this finding is about. */
+    readonly artifact: "manifest" | "docs" | "envExample" | "usage" | "evidence";
+    /** Absolute path the artifact would be written to. */
+    readonly path: string;
+    /** `"missing"` if the file doesn't exist yet, `"stale"` if it exists but differs from what a real run would produce. */
+    readonly status: "ok" | "stale" | "missing";
+    /** Human-readable detail, set for `"stale"`/`"missing"` findings. */
+    readonly detail?: string;
+}
+/** The result of a completed {@link checkEnvArtifacts} run. */
+export interface CheckEnvArtifactsResult {
+    /** `true` iff every requested artifact is `"ok"`. */
+    readonly ok: boolean;
+    /** One entry per requested artifact. */
+    readonly findings: readonly ArtifactCheckFinding[];
+}
+/**
+ * Parses `text` as an `EvidenceModel` and re-serializes it with
+ * `provenance.generatedAt` normalized out (see `normalizeEvidenceSnapshotForComparison()`)
+ * -- so `--check` never reports drift solely because a fresh render's
+ * timestamp differs from the committed file's. A parse failure returns
+ * `text` unchanged, so a corrupted on-disk file simply fails to match
+ * `expected`'s normalized form (reported as `"stale"`), rather than
+ * crashing `--check` itself.
+ */
+/** @internal Exported for direct unit coverage -- reached through `checkEnvArtifacts()`'s `--evidence` pass in production, but the exact "returns text unchanged, not undefined/thrown" catch behavior isn't independently observable through that public path (any malformed `actual` already reads as "stale" against a well-formed `expected`, regardless of the catch's exact return value). */
+export declare function normalizeEvidenceJsonForComparison(text: string): string;
+/**
+ * Verifies every requested artifact (`manifest`/`docs`/`envExample`/`usage`)
+ * matches what a real {@link generateEnvArtifacts} run would produce, without
+ * writing anything.
+ *
+ * @remarks
+ * `--check` reports drift, it doesn't paper over a run that would otherwise fail --
+ * see `@throws` below.
+ *
+ * @throws {EnvProjectGenerationError} On the same blocking findings a real run would throw on.
+ */
+export declare function checkEnvArtifacts(options: GenerateEnvArtifactsOptions): Promise<CheckEnvArtifactsResult>;
+//# sourceMappingURL=check-artifacts.d.ts.map

package/dist/.dts/build/check-artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-artifacts.d.ts","sourceRoot":"","sources":["../../../src/build/check-artifacts.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAA;AAU9E;;;;GAIG;AAEH,0EAA0E;AAC1E,MAAM,WAAW,oBAAoB;IACnC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,GAAG,YAAY,GAAG,OAAO,GAAG,UAAU,CAAA;IAC5E,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,wHAAwH;IACxH,QAAQ,CAAC,MAAM,EAAE,IAAI,GAAG,OAAO,GAAG,SAAS,CAAA;IAC3C,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,+DAA+D;AAC/D,MAAM,WAAW,uBAAuB;IACtC,qDAAqD;IACrD,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;IACpB,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAA;CACnD;AA6BD;;;;;;;;GAQG;AACH,oYAAoY;AACpY,wBAAgB,kCAAkC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOvE;AAqBD;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,uBAAuB,CAAC,CAyHlC"}

package/dist/.dts/build/citation-verification.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Re-verifies developer-declared `dynamicAccess` citations every run -- never
+ * trusted forever (ADR 0037). Two independent steps, kept as two separate
+ * functions rather than one, since they answer two different questions and
+ * the second is a pure read over the first's result:
+ *
+ * - `buildCitationSnapshots` (this run, I/O): for every currently-declared
+ *   citation, resolves the cited file and computes a whole-file SHA-256, then
+ *   compares it against the *previous* evidence snapshot's recorded hash to
+ *   label the citation `"fresh"` / `"stale"` / `"missing"`. Existence is
+ *   always re-checked live, never trusted from either snapshot. A citation
+ *   with no previous baseline (the first time it's ever been seen) is
+ *   `"fresh"` -- there is nothing to contradict it yet. Never throws on a
+ *   missing file; that citation is simply labeled `"missing"`.
+ * - `verifyDynamicAccessCitations` (pure): flattens that result down to just
+ *   the citations that need a human's attention -- every `"stale"`/`"missing"`
+ *   assertion, enriched with the owning contract's display name. These are the
+ *   direct input to `finding-model.ts`'s `STALE_DYNAMIC_ACCESS_CITATION` /
+ *   `MISSING_DYNAMIC_ACCESS_CITATION` findings.
+ *
+ * Deliberately separate from `evidence-snapshot.ts`'s own `diffContracts()`,
+ * which stays synchronous and pure -- these are the only filesystem-touching,
+ * citation-specific part of the evidence-snapshot lifecycle. A citation is
+ * always a developer's *re-acknowledgment* that access happens, never a claim
+ * env-cap itself observed anything: nothing here ever folds into the
+ * AST-derived `VariableAccessStatus`.
+ */
+import type { EvidenceModel } from "./evidence-model.js";
+import type { DiscoveredContract } from "./link.js";
+import type { DynamicAccessAssertion, SourcePosition } from "./source-position.js";
+/** Stable key {@link buildCitationSnapshots} and `dependency-graph.ts`'s consumer of it agree on -- `file` must be root-relative, POSIX-separated on both sides for a lookup to ever hit. */
+export declare function dynamicAccessVariableIdentity(file: string, exportName: string, key: string): string;
+/**
+ * Re-checks every current `dynamicAccess` citation against the previous
+ * evidence snapshot's committed `contentHash` baseline. Existence is always
+ * re-checked live (never trusted from either snapshot); content drift is
+ * only detectable when a previous baseline exists at all -- a citation with
+ * no previous baseline (first time it's ever been seen) is reported
+ * `"fresh"`, matching the same "nothing to contradict yet" logic. See ADR
+ * 0037.
+ */
+export declare function buildCitationSnapshots(activeContracts: readonly DiscoveredContract[], previous: EvidenceModel | undefined, root: string, readFile: (filePath: string) => Promise<string>): Promise<ReadonlyMap<string, readonly DynamicAccessAssertion[]>>;
+/** One `dynamicAccess` citation env-cap can no longer vouch for -- the direct input to `finding-model.ts`'s `"STALE_DYNAMIC_ACCESS_CITATION"`/`"MISSING_DYNAMIC_ACCESS_CITATION"` findings. See ADR 0037. */
+export interface DynamicAccessCitationProblem {
+    readonly contractName: string;
+    /** Root-relative, POSIX-separated. */
+    readonly file: string;
+    readonly exportName: string;
+    /** The variable whose `dynamicAccess` citation this is. */
+    readonly key: string;
+    /** Where the citation points -- not the variable's own declaration. */
+    readonly position: SourcePosition;
+    readonly acknowledgment: "stale" | "missing";
+}
+/**
+ * Flattens {@link buildCitationSnapshots}' result down to just the citations
+ * that need attention -- every `"stale"`/`"missing"` assertion, enriched with
+ * the owning contract's display name. `"fresh"` assertions are silently
+ * omitted -- nothing to report about a citation that's still trustworthy.
+ */
+export declare function verifyDynamicAccessCitations(activeContracts: readonly DiscoveredContract[], root: string, acknowledgments: ReadonlyMap<string, readonly DynamicAccessAssertion[]>): readonly DynamicAccessCitationProblem[];
+//# sourceMappingURL=citation-verification.d.ts.map

package/dist/.dts/build/citation-verification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citation-verification.d.ts","sourceRoot":"","sources":["../../../src/build/citation-verification.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAExD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAEnD,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAOlF,6LAA6L;AAC7L,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,GACV,MAAM,CAER;AAkCD;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,eAAe,EAAE,SAAS,kBAAkB,EAAE,EAC9C,QAAQ,EAAE,aAAa,GAAG,SAAS,EACnC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAC9C,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAC,CAAC,CAiDjE;AAED,6MAA6M;AAC7M,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAA;IACjC,QAAQ,CAAC,cAAc,EAAE,OAAO,GAAG,SAAS,CAAA;CAC7C;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,eAAe,EAAE,SAAS,kBAAkB,EAAE,EAC9C,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAC,GACtE,SAAS,4BAA4B,EAAE,CA8BzC"}

package/dist/.dts/build/compatibility.d.ts

@@ -0,0 +1,76 @@
+import type { DiscoveredContract } from "./link.js";
+/**
+ * Every stable `code` a check in this file (or `exclusive-group.ts`) can
+ * emit. Documented as an enumerated union so a consumer filtering/linking on
+ * `code` has a closed list to switch over, rather than an arbitrary string --
+ * see ADR 0024/0026. `exclusive-group.ts`'s check does not (yet) set one; see
+ * that file's own comment for why.
+ */
+export type CompatibilityIssueCode = "PROCESSOR_RETURN_TYPE_CONFLICT" | "PROCESSOR_SOURCE_CONFLICT" | "VALIDATOR_SOURCE_CONFLICT" | "DUPLICATE_VARIABLE_DOCUMENTATION" | "DUPLICATE_VARIABLE_SHAPE_ACROSS_CONTRACTS";
+/** One compatibility problem found between two or more declarations of the same variable, or an exclusive-group violation. */
+export interface CompatibilityIssue {
+    /** `"error"` blocks generation regardless of `onIncompatibility`; `"warning"` blocks only when `onIncompatibility: "throw"`; `"info"` never blocks, under any flag. */
+    readonly severity: "error" | "warning" | "info";
+    /** The environment variable name, or `"(contract) <name>"` for a contract-level (e.g. exclusive-group) issue. */
+    readonly variable: string;
+    /** Every file declaring a conflicting definition. */
+    readonly files: readonly string[];
+    /** Human-readable explanation of the conflict. */
+    readonly reason: string;
+    /**
+     * Stable, machine-readable identifier for CI filtering / doc-linking /
+     * GitHub Action annotations / IDE integration. `undefined` only for checks
+     * that don't (yet) set one -- see {@link CompatibilityIssueCode} for the
+     * full enumerated list of values a check in this file can produce.
+     */
+    readonly code?: CompatibilityIssueCode;
+}
+/**
+ * Flags cases where two contracts declare the same variable name but appear to
+ * disagree about its shape, so a human can confirm they're still meant to be "the same" var.
+ *
+ * @remarks
+ * Duplicate variable names across contracts are not a merge problem -- each
+ * contract independently processes its own copy of the raw value, there is no
+ * runtime merge at all. This is purely a build-time lint.
+ *
+ * Only one thing is treated as *provable* without executing code: two
+ * processors with explicit, differing `: T` return type annotations. That is
+ * a hard error. Everything else (differing processor/validator source text
+ * with no annotation, or none at all) is a warning -- we cannot prove
+ * semantic non-equivalence via static analysis alone, and the library never
+ * executes schema code to check further (see literal-eval.ts).
+ */
+export declare function detectCompatibilityIssues(contracts: readonly DiscoveredContract[]): CompatibilityIssue[];
+/**
+ * Flags *differently-named* variables in different contracts that share an
+ * identical type shape -- a soft signal that two features may be
+ * independently modelling the same underlying configuration value under two
+ * names, worth a human glance before they drift apart.
+ *
+ * @remarks
+ * Always `severity: "info"`, and never escalated to blocking by any flag,
+ * including `--strict` -- an identical shape is genuinely common and
+ * frequently correct (two unrelated features can both take a `number` timeout
+ * with a validator, and that is not a defect). This is an observation offered
+ * to a reader, not a rule; making it blockable would make it noise a team has
+ * to suppress rather than a signal they can scan.
+ *
+ * Scope, deliberately narrow on every axis:
+ *  - **Different keys only.** Same-key collisions across contracts are
+ *    `detectCompatibilityIssues()`'s own, entirely separate concern above;
+ *    reporting them here too would double-report one problem under two codes.
+ *  - **Different contracts only.** Two same-shaped variables inside one
+ *    contract are that contract's own deliberate design.
+ *  - **Active contracts only.** An inactive contract is wired into nothing,
+ *    so an overlap with it is not a live duplication.
+ *  - **No exclusive-grouped contracts.** Members of an exclusive group are
+ *    interchangeable alternatives by explicit authorial declaration --
+ *    matching shapes there are the *point*, not a smell.
+ *  - **Pairwise, never transitive.** Three mutually-matching variables emit
+ *    three independent findings (A-B, A-C, B-C), never one merged "cluster":
+ *    each pair is its own question a reader answers on its own, and a cluster
+ *    would imply a transitive relationship this check never established.
+ */
+export declare function detectDuplicateVariableShapes(contracts: readonly DiscoveredContract[]): CompatibilityIssue[];
+//# sourceMappingURL=compatibility.d.ts.map

package/dist/.dts/build/compatibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compatibility.d.ts","sourceRoot":"","sources":["../../../src/build/compatibility.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAsB,MAAM,WAAW,CAAA;AAEvE;;;;;;GAMG;AACH,MAAM,MAAM,sBAAsB,GAC9B,gCAAgC,GAChC,2BAA2B,GAC3B,2BAA2B,GAC3B,kCAAkC,GAClC,2CAA2C,CAAA;AAE/C,8HAA8H;AAC9H,MAAM,WAAW,kBAAkB;IACjC,uKAAuK;IACvK,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAA;IAC/C,iHAAiH;IACjH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,sBAAsB,CAAA;CACvC;AA0BD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,SAAS,kBAAkB,EAAE,GACvC,kBAAkB,EAAE,CAqGtB;AA6DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,SAAS,kBAAkB,EAAE,GACvC,kBAAkB,EAAE,CAuDtB"}