@maverickcer/env-cap 0.2.0

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

@@ -0,0 +1,92 @@
+import { type EnvGovernanceFields } from "./governance-fields.js";
+import type { DiscoveredContract } from "./link.js";
+import type { DiscoveredVariableEvidence } from "./parse.js";
+import type { PackageOrigin } from "./resolution/resolve-package-schema.js";
+import type { SourcePosition } from "./source-position.js";
+/**
+ * The first of env-cap's seven canonical fact models (ADR 0024) -- a
+ * versioned, JSON-serializable projection of every declared environment
+ * variable's structural and documentation contract. See ADR 0025.
+ *
+ * @remarks
+ * Deliberately broader than the persisted evidence snapshot's
+ * (`evidence-snapshot.ts`) `ManifestChangeReport` scope: that diff is scoped
+ * to *active* contracts and *only* the `documentEnv()`-sourced fields,
+ * matching `renderManifest()`'s own scope (ADR 0021). This model includes
+ * every discovered contract regardless of `active`, plus the AST-derived
+ * schema facts (`hasDefault`/`hasProcessor`/etc.) the change report
+ * deliberately excludes -- both are load-bearing for downstream
+ * Finding/Evidence Model work.
+ */
+/** Bump only when a reader could misinterpret the new shape (a field changes
+ *  type/meaning, or is removed) -- NOT for every additive field. Same
+ *  discipline `evidence-model.ts`'s `EVIDENCE_MODEL_SCHEMA_VERSION` and
+ *  `src/cli/json.ts`'s `JSON_SCHEMA_VERSION` already document. */
+export declare const CONTRACT_MODEL_SCHEMA_VERSION = 3;
+/**
+ * One variable's full statically-discoverable contract: schema-shaped facts plus linked documentation.
+ *
+ * @see {@link DependencyModelVariable} -- this same declared variable's access status.
+ * @see {@link OwnershipModelVariable} -- this same declared variable's effective owner.
+ * @see {@link LifecycleModelVariable} -- this same declared variable's lifecycle data.
+ * @see `CatalogVariable` (`docs.ts`) -- this same declared variable, reshaped for the generated
+ * docs catalog/JSON. Plain reference, not `{@link}`: `CatalogVariable` is intentionally not part
+ * of the public surface (see `typedoc.json`'s `intentionallyNotExported`).
+ */
+export interface ContractModelVariable extends EnvGovernanceFields {
+    readonly key: string;
+    readonly hasDefault: boolean;
+    readonly defaultValue: {
+        readonly ok: true;
+        readonly value: unknown;
+    } | {
+        readonly ok: false;
+    } | undefined;
+    readonly hasProcessor: boolean;
+    readonly processorSource: string | undefined;
+    readonly processorReturnType: string | undefined;
+    readonly hasValidator: boolean;
+    readonly validatorSource: string | undefined;
+    readonly context: string | undefined;
+    readonly description: string | undefined;
+    readonly refreshInstructions: string | undefined;
+    readonly setupInstructions: string | undefined;
+    readonly required: boolean | undefined;
+    readonly documented: boolean;
+    /** The `evidence` sub-object from this variable's linked documentation -- re-verified every run, unlike every declared-only field above. See {@link runtime.VariableEvidenceDocs} and ADR 0037. */
+    readonly evidence: DiscoveredVariableEvidence | undefined;
+    /** Where this variable's own schema property is declared. See ADR 0036. */
+    readonly declaration: SourcePosition;
+}
+/** One `createEnv()` contract's full statically-discoverable contract, active or not. */
+export interface ContractModelContract extends EnvGovernanceFields {
+    /** Root-relative, POSIX-separated -- matches `DiscoveredContractSummary.file`. */
+    readonly file: string;
+    readonly exportName: string;
+    readonly contractName: string;
+    readonly active: boolean;
+    readonly category: string | undefined;
+    readonly exclusiveGroup: string | undefined;
+    readonly variables: readonly ContractModelVariable[];
+    readonly documented: boolean;
+    readonly packageOrigin: PackageOrigin | undefined;
+    /** Where this contract's `createEnv(...)` call is declared. Always present. See ADR 0036. */
+    readonly declaration: SourcePosition;
+    /** Where this contract's `documentEnv(...)` call is declared, if one exists. See ADR 0036. */
+    readonly documentation: SourcePosition | undefined;
+}
+export interface ContractModel {
+    readonly schemaVersion: typeof CONTRACT_MODEL_SCHEMA_VERSION;
+    readonly contracts: readonly ContractModelContract[];
+}
+/**
+ * Projects every discovered contract (active or not) into the Contract
+ * Model's versioned, JSON-serializable shape.
+ *
+ * @remarks
+ * Sorted deterministically (by file, then exportName, then variable key), so
+ * `JSON.stringify` output is stable and diffs cleanly wherever this is
+ * persisted.
+ */
+export declare function buildContractModel(contracts: readonly DiscoveredContract[], root: string): ContractModel;
+//# sourceMappingURL=contract-model.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"contract-model.d.ts","sourceRoot":"","sources":["../../../src/build/contract-model.ts"],"names":[],"mappings":"AAEA,OAAO,EAAsB,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AACrF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAA;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAA;AAC3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAmB1D;;;;;;;;;;;;;;GAcG;AAEH;;;kEAGkE;AAClE,eAAO,MAAM,6BAA6B,IAAI,CAAA;AAE9C;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAsB,SAAQ,mBAAmB;IAChE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,YAAY,EACnB;QAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG;QAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAA;KAAE,GAAG,SAAS,CAAA;IACrF,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5C,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAA;IAChD,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAA;IAChD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9C,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,mMAAmM;IACnM,QAAQ,CAAC,QAAQ,EAAE,0BAA0B,GAAG,SAAS,CAAA;IACzD,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAA;CACrC;AAED,yFAAyF;AACzF,MAAM,WAAW,qBAAsB,SAAQ,mBAAmB;IAChE,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3C,QAAQ,CAAC,SAAS,EAAE,SAAS,qBAAqB,EAAE,CAAA;IACpD,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,aAAa,EAAE,aAAa,GAAG,SAAS,CAAA;IACjD,6FAA6F;IAC7F,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAA;IACpC,8FAA8F;IAC9F,QAAQ,CAAC,aAAa,EAAE,cAAc,GAAG,SAAS,CAAA;CACnD;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,aAAa,EAAE,OAAO,6BAA6B,CAAA;IAC5D,QAAQ,CAAC,SAAS,EAAE,SAAS,qBAAqB,EAAE,CAAA;CACrD;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,IAAI,EAAE,MAAM,GACX,aAAa,CAmDf"}

package/dist/.dts/build/deep-equal.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Structural equality for JSON-safe values -- `documentEnv()`'s `metadata` can hold an
+ * object/array (ADR 0035), so two independently-declared-but-identical values are never `===`.
+ * Values compared here are always JSON-safe (string/number/boolean/null/array/object,
+ * recursively -- see `literal-eval.ts`), so this doesn't need to handle cycles, `Date`, `Map`, or
+ * anything else `evaluateLiteral()` can never produce.
+ */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+//# sourceMappingURL=deep-equal.d.ts.map

package/dist/.dts/build/deep-equal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-equal.d.ts","sourceRoot":"","sources":["../../../src/build/deep-equal.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAezD"}

package/dist/.dts/build/deep-freeze.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Recursively freezes `value` and everything reachable from it (array
+ * elements, plain-object property values), so a mutation anywhere in the
+ * structure throws instead of silently succeeding.
+ *
+ * @remarks
+ * Generalized from `live-expirations.ts`'s former `DiscoveredContract[]`-
+ * hardcoded `deepFreezeContracts()` (see ADR 0012) into a truly generic
+ * utility, so Evidence Model's own immutability guarantee (a later phase)
+ * can reuse it instead of duplicating the recursion.
+ *
+ * Only recurses into arrays and plain objects (`{}` or `Object.create(null)`)
+ * -- a `Map`, `Set`, or class instance is frozen at its own top level but not
+ * walked further. This codebase's fact models are plain JSON-serializable
+ * data, never class instances, so this is deliberately narrow rather than a
+ * general-purpose deep-freeze library. A `WeakSet` guards against infinite
+ * recursion if a cyclic reference is ever passed in.
+ */
+export declare function deepFreeze<T>(value: T): T;
+//# sourceMappingURL=deep-freeze.d.ts.map

package/dist/.dts/build/deep-freeze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-freeze.d.ts","sourceRoot":"","sources":["../../../src/build/deep-freeze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAEzC"}

package/dist/.dts/build/dependency-graph.d.ts

@@ -0,0 +1,168 @@
+import type { EscapeReason } from "./scan-dependencies.js";
+import type { ImportResolutionContext } from "./resolution/resolve-import.js";
+import type { DiscoveredContract } from "./link.js";
+import type { ParseWarning } from "./parse.js";
+import type { DynamicAccessAssertion, SourcePosition } from "./source-position.js";
+/**
+ * What env-cap's static scan could prove about one variable's consumption:
+ * it was member-accessed somewhere (`"used"`), it was never accessed at all
+ * within the scanned surfaces (`"unconsumed"`), or a computed (dynamic)
+ * property access on the owning contract makes the answer unprovable
+ * (`"indeterminate"`).
+ *
+ * @remarks
+ * Deliberately narrower than `@maverickcer/data-cap`'s equivalent, which
+ * splits the unprovable case further (an unresolved *consumer* vs. an
+ * indeterminate *field*). That split exists because a data-cap capability
+ * exposes many fields at once, so it has a real "we resolved the consumer,
+ * but can't tell which field it touched" state to name. env-cap's
+ * consumption model is one value per key: a contract member access either
+ * names the key statically (`"used"`) or it doesn't (`"indeterminate"`), and
+ * there is no intermediate case where the consumer is known but the thing
+ * consumed is ambiguous. Adding a fourth state here would be vocabulary
+ * borrowed from a model env-cap doesn't have -- see ADR 0010's
+ * "provable, not heuristic" rule. Developer-declared `dynamicAccess`
+ * citations stay a wholly separate fact and are never folded into this
+ * status (ADR 0037).
+ */
+export type VariableAccessStatus = "used" | "unconsumed" | "indeterminate";
+/**
+ * Every reason `deriveOwnershipFindings` can cite for an `indeterminate`
+ * variable, cited on the {@link EscapeSite} the scanner actually observed --
+ * `EscapeReason` (destructuring/aliasing shapes the scanner declines to
+ * follow, see ADR 0039) plus `"reference"` for a tracked import/alias
+ * mentioned bare (passed as an argument, spread, assigned elsewhere, ...):
+ * a real, provable read of the contract that this single-file walk simply
+ * can't attribute to any specific key.
+ */
+type EscapeVia = EscapeReason | "reference";
+/** One position where a tracked contract's value escaped this scanner's local dataflow analysis -- see {@link EscapeVia}. */
+interface EscapeSite extends SourcePosition {
+    readonly via: EscapeVia;
+}
+interface VariableAccessInfo {
+    readonly status: VariableAccessStatus;
+    /** Internal only, never exposed publicly -- which AST evidence produced
+     *  this status, so a future "why does env-cap think this is
+     *  unconsumed" bug report is debuggable without re-deriving the AST walk
+     *  by hand. */
+    readonly evidence: "member-access" | "dynamic-access" | "escape" | "no-access";
+    /** Every position where a member access was observed for this variable,
+     *  aggregated across every consuming file -- empty unless
+     *  `status === "used"`. Previously computed by `scan-dependencies.ts`'s
+     *  `AccessSite` and discarded before reaching even this internal type;
+     *  threaded through as of ADR 0027 (line only) and ADR 0036 (full
+     *  position, one entry per file rather than a flat, file-less list of
+     *  line numbers) so `dependency-model.ts` can publish it. */
+    readonly positions: readonly SourcePosition[];
+    /** Every developer-declared `dynamicAccess` citation's current freshness for this variable -- a wholly separate, independent fact from `status`/`evidence` above, never folded into them. Empty unless the linked `documentEnv()` call declared at least one citation for this key. See ADR 0037. */
+    readonly dynamicAccessAssertions: readonly DynamicAccessAssertion[];
+}
+/** One named surface `buildDependencyGraph()`'s scan actually covered -- the
+ *  application's own root, plus one entry per allow-listed `packages` (ADR
+ *  0014) name whose source was also scanned. See ADR 0036: a claim like
+ *  "no consumer found" is only ever as strong as what was actually
+ *  searched, and this is what lets a renderer say so explicitly instead of
+ *  implying an unbounded guarantee it can't back up. */
+export interface ScannedSurface {
+    /** `"application"` for the local project root, `"package:<name>"` for an allow-listed package's own source. */
+    readonly label: string;
+    /** Root-relative, POSIX-separated. */
+    readonly root: string;
+}
+interface ContractDependencySummary {
+    readonly file: string;
+    readonly exportName: string;
+    readonly contractName: string;
+    readonly imported: boolean;
+    readonly hasDynamicAccess: boolean;
+    /** Every declared key is always present. */
+    readonly variables: ReadonlyMap<string, VariableAccessInfo>;
+    /** Every file coupled to this contract -- contract-level "who depends on
+     *  this," not proof any specific variable was read. See the
+     *  consumer-vs-variable-access semantics note in `deriveOwnershipFindings`. */
+    readonly consumingFiles: readonly string[];
+    /** Files whose import of this contract's name couldn't be verified
+     *  because it resolved through a file containing an unresolved wildcard
+     *  re-export. */
+    readonly ambiguousBarrelFiles: readonly string[];
+    /** Every computed (dynamic) property-access site observed anywhere on
+     *  this contract -- previously collapsed into `hasDynamicAccess` alone
+     *  and discarded; threaded through as of ADR 0036 so a finding can cite
+     *  exactly where the uncertainty comes from instead of just asserting it
+     *  exists. */
+    readonly dynamicAccessSites: readonly SourcePosition[];
+    /** Every position where the contract's value flowed somewhere this
+     *  scanner's local dataflow analysis can't follow -- see {@link
+     *  EscapeVia} and ADR 0039. Like `dynamicAccessSites`, this widens every
+     *  not-otherwise-accessed variable on the SAME contract to
+     *  `indeterminate`, never `unconsumed`. */
+    readonly escapeSites: readonly EscapeSite[];
+}
+export interface DependencyGraph {
+    readonly contracts: readonly ContractDependencySummary[];
+    readonly warnings: readonly ParseWarning[];
+    /** Every surface actually scanned for usage -- see {@link ScannedSurface}. Always has at least one entry (the application root). */
+    readonly scannedSurfaces: readonly ScannedSurface[];
+}
+export declare function buildDependencyGraph(contracts: readonly DiscoveredContract[], scanFiles: readonly string[], readFile: (filePath: string) => Promise<string>, context: ImportResolutionContext, scannedSurfaces?: readonly ScannedSurface[], dynamicAccessAcknowledgments?: ReadonlyMap<string, readonly DynamicAccessAssertion[]>): Promise<DependencyGraph>;
+interface AbandonedOwnershipFinding {
+    readonly file: string;
+    readonly exportName: string;
+    readonly contractName: string;
+}
+interface UnresolvedConsumerOwnershipFinding extends AbandonedOwnershipFinding {
+    readonly reason: string;
+}
+interface UnconsumedOwnedVariableOwnershipFinding extends AbandonedOwnershipFinding {
+    readonly key: string;
+}
+interface IndeterminateAccessOwnershipFinding extends AbandonedOwnershipFinding {
+    readonly key: string;
+    readonly reason: string;
+    /** Every AST-observed dynamic-access site on this contract -- see ADR 0036. */
+    readonly dynamicAccessSites: readonly SourcePosition[];
+    /** Every AST-observed escape site on this contract -- see {@link EscapeVia} and ADR 0039. */
+    readonly escapeSites: readonly EscapeSite[];
+}
+/** A variable that would otherwise be `unconsumedOwned`/`indeterminate`, but has at least one `"fresh"` developer-declared `dynamicAccess` assertion -- the "asserted" category (ADR 0037). Never silently dropped: the raw `wouldBeStatus` is always shown alongside the assertion, per Design 7's "never let a claim overwrite an observation" rule. */
+interface AssertedOwnershipFinding extends AbandonedOwnershipFinding {
+    readonly key: string;
+    readonly wouldBeStatus: "unconsumed" | "indeterminate";
+    readonly dynamicAccessAssertions: readonly DynamicAccessAssertion[];
+}
+export interface OwnershipFindings {
+    readonly abandoned: readonly AbandonedOwnershipFinding[];
+    readonly unresolvedConsumers: readonly UnresolvedConsumerOwnershipFinding[];
+    readonly unconsumedOwned: readonly UnconsumedOwnedVariableOwnershipFinding[];
+    readonly indeterminate: readonly IndeterminateAccessOwnershipFinding[];
+    readonly asserted: readonly AssertedOwnershipFinding[];
+}
+/**
+ * Derives ownership findings from the graph. This is where the epistemic
+ * rules that matter most live:
+ *  - A contract never imported anywhere, with no ambiguous barrel path
+ *    either, is `abandoned` -- a feature's schema outliving the feature.
+ *  - A contract never *directly* imported, but reachable only through an
+ *    unresolved barrel re-export, is `unresolvedConsumers` -- never
+ *    `abandoned`. Claiming "abandoned" here would be a false positive with
+ *    real consequences.
+ *  - A variable with no member access anywhere, on a contract with no
+ *    dynamic access anywhere, is `unconsumedOwned` -- "no consumer found in
+ *    this repository," not "provably dead." The scanned surfaces are named
+ *    explicitly in the reason, per ADR 0036, so the claim is exactly as
+ *    strong as what was actually searched.
+ *  - A variable with no member access, but dynamic access observed
+ *    *somewhere* on that contract, is `indeterminate` -- never
+ *    `unconsumedOwned`. Uncertainty is never promoted to certainty in either
+ *    direction. Every candidate dynamic-access site is cited by name.
+ *  - A variable with at least one `"fresh"` {@link DynamicAccessAssertion}
+ *    (ADR 0037) gets neither `unconsumedOwned` nor `indeterminate`, regardless
+ *    of `status` -- a developer has re-acknowledged the access exists. The
+ *    Dependency Model itself still keeps `status` and the assertion side by
+ *    side, unedited; only *this* finding-suppression decision reads them
+ *    together.
+ */
+export declare function deriveOwnershipFindings(graph: DependencyGraph): OwnershipFindings;
+export {};
+//# sourceMappingURL=dependency-graph.d.ts.map

package/dist/.dts/build/dependency-graph.d.ts.map

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

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

@@ -0,0 +1,79 @@
+import type { ContractRef } from "./evidence-reference.js";
+import type { ScannedSurface, VariableAccessStatus } from "./dependency-graph.js";
+import type { DiscoveredContract } from "./link.js";
+import type { ParseWarning } from "./parse.js";
+import type { ImportResolutionContext } from "./resolution/resolve-import.js";
+import type { DynamicAccessAssertion, SourcePosition } from "./source-position.js";
+/**
+ * The second of env-cap's seven canonical fact models (ADR 0024) -- a
+ * versioned, JSON-serializable projection of the dependency-ownership
+ * engine's graph. See ADR 0027 and ADR 0036.
+ *
+ * @remarks
+ * `dependency-graph.ts`'s scanning/graph-building internals stay Private,
+ * unchanged, per ADR 0010 -- this is a fact-shaped *result* built on top of
+ * them, not a relaxation of that boundary. Graph-format rendering (DOT,
+ * Mermaid, a `{nodes, edges}` JSON export) is deliberately not here --
+ * that's presentation over this model's data, not the model itself.
+ */
+/** Bump only when a reader could misinterpret the new shape -- same discipline every other canonical model's `schemaVersion` follows. */
+export declare const DEPENDENCY_MODEL_SCHEMA_VERSION = 2;
+/**
+ * One variable's access status within a contract, plus every position it was found
+ * member-accessed at, aggregated across every consuming file.
+ *
+ * @see {@link ContractModelVariable} -- this same declared variable's canonical starting point.
+ */
+export interface DependencyModelVariable {
+    readonly key: string;
+    readonly status: VariableAccessStatus;
+    /** Empty unless `status === "used"`. Previously discarded before reaching any public type -- see ADR 0027 (line only) and ADR 0036 (full position, file included per entry). */
+    readonly positions: readonly SourcePosition[];
+    /** Every developer-declared `dynamicAccess` citation's current freshness for this variable -- a wholly separate, independent fact from `status` above, never folded into it. Empty when no citation was declared, or when no manifest snapshot baseline was available to check against (the manifest pass wasn't also requested). See ADR 0037. */
+    readonly dynamicAccessAssertions: readonly DynamicAccessAssertion[];
+}
+export interface DependencyModelContract {
+    /** Root-relative, POSIX-separated -- matches `ContractModelContract.file`. */
+    readonly file: string;
+    readonly exportName: string;
+    readonly contractName: string;
+    readonly imported: boolean;
+    readonly hasDynamicAccess: boolean;
+    readonly variables: readonly DependencyModelVariable[];
+    /** Every file coupled to this contract -- contract-level "who depends on this," not proof any specific variable was read. */
+    readonly consumingFiles: readonly string[];
+    /** Files whose import of this contract's name couldn't be verified because it resolved through a file containing an unresolved wildcard re-export. */
+    readonly ambiguousBarrelFiles: readonly string[];
+    /** Every computed (dynamic) property-access site observed anywhere on this contract -- see ADR 0036. */
+    readonly dynamicAccessSites: readonly SourcePosition[];
+}
+/** One contract, as referenced from the inverse (`consumers`) index -- see {@link ContractRef} for why no `contractName` is carried here. */
+export type DependencyModelContractRef = ContractRef;
+/** One consuming file, and every contract it depends on -- the inverse of `DependencyModelContract.consumingFiles`. */
+export interface DependencyModelConsumer {
+    /** Root-relative, POSIX-separated. */
+    readonly file: string;
+    readonly contracts: readonly DependencyModelContractRef[];
+}
+export interface DependencyModel {
+    readonly schemaVersion: typeof DEPENDENCY_MODEL_SCHEMA_VERSION;
+    readonly contracts: readonly DependencyModelContract[];
+    /** Inverse of `contracts[].consumingFiles` -- one entry per file that consumes at least one contract, listing which contracts it reads. */
+    readonly consumers: readonly DependencyModelConsumer[];
+    readonly warnings: readonly ParseWarning[];
+    /** Every surface actually scanned for usage -- see ADR 0036. Always has at least one entry (the application root). */
+    readonly scannedSurfaces: readonly ScannedSurface[];
+}
+/**
+ * Runs the dependency-ownership engine (`buildDependencyGraph()`, Private)
+ * and projects its result into the Dependency Model's versioned,
+ * JSON-serializable shape -- including the inverse file-\>contracts index
+ * neither `dependency-graph.ts` nor `usage-report.ts` exposes today.
+ *
+ * @param scannedSurfaces - See `buildDependencyGraph()`'s own parameter of
+ * the same name -- passed straight through to the published model.
+ * @param dynamicAccessAcknowledgments - See `buildDependencyGraph()`'s own
+ * parameter of the same name (ADR 0037) -- passed straight through.
+ */
+export declare function buildDependencyModel(contracts: readonly DiscoveredContract[], scanFiles: readonly string[], readFile: (filePath: string) => Promise<string>, context: ImportResolutionContext, root: string, scannedSurfaces?: readonly ScannedSurface[], dynamicAccessAcknowledgments?: ReadonlyMap<string, readonly DynamicAccessAssertion[]>): Promise<DependencyModel>;
+//# sourceMappingURL=dependency-model.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dependency-model.d.ts","sourceRoot":"","sources":["../../../src/build/dependency-model.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAE1D,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AACjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAA;AAC7E,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAElF;;;;;;;;;;;GAWG;AAEH,yIAAyI;AACzI,eAAO,MAAM,+BAA+B,IAAI,CAAA;AAEhD;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAA;IACrC,gLAAgL;IAChL,QAAQ,CAAC,SAAS,EAAE,SAAS,cAAc,EAAE,CAAA;IAC7C,mVAAmV;IACnV,QAAQ,CAAC,uBAAuB,EAAE,SAAS,sBAAsB,EAAE,CAAA;CACpE;AAED,MAAM,WAAW,uBAAuB;IACtC,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAA;IAClC,QAAQ,CAAC,SAAS,EAAE,SAAS,uBAAuB,EAAE,CAAA;IACtD,6HAA6H;IAC7H,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C,sJAAsJ;IACtJ,QAAQ,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAA;IAChD,wGAAwG;IACxG,QAAQ,CAAC,kBAAkB,EAAE,SAAS,cAAc,EAAE,CAAA;CACvD;AAED,6IAA6I;AAC7I,MAAM,MAAM,0BAA0B,GAAG,WAAW,CAAA;AAEpD,uHAAuH;AACvH,MAAM,WAAW,uBAAuB;IACtC,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,SAAS,0BAA0B,EAAE,CAAA;CAC1D;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,aAAa,EAAE,OAAO,+BAA+B,CAAA;IAC9D,QAAQ,CAAC,SAAS,EAAE,SAAS,uBAAuB,EAAE,CAAA;IACtD,2IAA2I;IAC3I,QAAQ,CAAC,SAAS,EAAE,SAAS,uBAAuB,EAAE,CAAA;IACtD,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAA;IAC1C,sHAAsH;IACtH,QAAQ,CAAC,eAAe,EAAE,SAAS,cAAc,EAAE,CAAA;CACpD;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,EAC/C,OAAO,EAAE,uBAAuB,EAChC,IAAI,EAAE,MAAM,EACZ,eAAe,CAAC,EAAE,SAAS,cAAc,EAAE,EAC3C,4BAA4B,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAC,GACpF,OAAO,CAAC,eAAe,CAAC,CAiE1B"}

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

@@ -0,0 +1,25 @@
+import type { BuildFileSystem } from "./types.js";
+/** Options for {@link discoverSchemaFiles}. */
+export interface DiscoverOptions {
+    /** The filesystem capability -- `./build` never imports `node:fs` (ADR 0040). */
+    readonly fs: BuildFileSystem;
+    /** Absolute path to search under. */
+    readonly root: string;
+    /** Glob patterns (relative to `root`) a file must match at least one of to be included. */
+    readonly include: readonly string[];
+    /** Glob patterns (relative to `root`) that prune a file or directory regardless of `include`. */
+    readonly exclude: readonly string[];
+}
+/**
+ * Finds every schema file matching `include`/`exclude` under `root`, returned
+ * as absolute paths in deterministic (alphabetically sorted) order.
+ *
+ * @remarks
+ * No external glob dependency: directories are pruned *during* the walk
+ * (both a hardcoded node_modules/.git skip and the caller's `exclude`
+ * patterns), rather than walked in full and filtered afterward -- walking an
+ * entire node_modules tree just to discard it is not acceptable for a tool
+ * meant to run against real projects.
+ */
+export declare function discoverSchemaFiles(options: DiscoverOptions): Promise<string[]>;
+//# sourceMappingURL=discover.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../../src/build/discover.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,+CAA+C;AAC/C,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAA;IAC5B,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,iGAAiG;IACjG,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC;AAUD;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAoBrF"}

package/dist/.dts/build/display-path.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Renders an absolute path for a human-facing generated artifact
+ * (`ENVIRONMENT.md`/`OWNERSHIP.md`) or a root-relative canonical model field,
+ * root-relative when possible. The one place this conversion lives -- every
+ * model builder and renderer that needs "the path as a reader should see it"
+ * goes through this, so two of them can never disagree about the form of the
+ * same file's path (which would silently break every `${file}#${exportName}`
+ * lookup that crosses between them).
+ *
+ * A `DiscoveredContract.file` keeps its own absolute path untouched -- that's
+ * the correct, unambiguous fact, and what stays sane when discovery spans
+ * multiple roots (a `packages`-discovered file living outside `root`
+ * entirely, ADR 0014).
+ */
+/**
+ * Renders `absolutePath` relative to `root`, POSIX-separated regardless of
+ * platform (matching every other rendered path in this package's Markdown and
+ * JSON output). Falls back to `absolutePath` itself, unchanged, whenever the
+ * result would need to climb outside `root` (a `packages`-discovered file, or
+ * any other path not under root) -- never manufactures a `../` escape, which
+ * reads as a real relative path to a consumer and resolves to nothing useful.
+ */
+export declare function displayPath(root: string, absolutePath: string): string;
+//# sourceMappingURL=display-path.d.ts.map

package/dist/.dts/build/display-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"display-path.d.ts","sourceRoot":"","sources":["../../../src/build/display-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAItE"}

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

@@ -0,0 +1,176 @@
+import type { ContractModelContract } from "./contract-model.js";
+import { type EnvGovernanceFields } from "./governance-fields.js";
+import type { DiscoveredVariableEvidence } from "./parse.js";
+/** Identifies a contract with no linked `documentEnv()` call at all. `file`'s absolute-vs-relative convention depends on where a given instance comes from -- see the specific field using this type (`DocumentationFindings.undocumentedContracts` is absolute; `RenderDocsOptions.undocumentedContracts` must be root-relative, matching the `ContractModel`-shaped `contracts` it's compared against). */
+export interface UndocumentedContractRef {
+    readonly file: string;
+    /** The contract's exported binding name. */
+    readonly exportName: string;
+}
+/** Identifies a schema variable with no matching entry in its contract's linked documentation. See {@link UndocumentedContractRef}'s own note on `file`. */
+export interface UndocumentedVariableRef {
+    readonly file: string;
+    /** The contract's exported binding name. */
+    readonly exportName: string;
+    /** The undocumented environment variable name. */
+    readonly key: string;
+}
+/** One contract- or variable-level `expiresAt` falling within the configured "expiring soon" window. */
+export interface ExpiringEntry {
+    /** Absolute path of the file declaring the contract. */
+    readonly file: string;
+    /** The contract's exported binding name. */
+    readonly exportName: string;
+    /** `undefined` for a contract-level `expiresAt`, set for a per-variable one. */
+    readonly key: string | undefined;
+    /** The raw ISO date string, unparsed. */
+    readonly expiresAt: string;
+    /** Days from `now` until expiry; negative when already expired. */
+    readonly daysRemaining: number;
+}
+/** Options for {@link renderDocs}. */
+export interface RenderDocsOptions {
+    /** How many days out counts as "expiring soon" in the lifecycle report and security review. */
+    readonly expiringWithinDays: number;
+    /** Contracts with no linked `documentEnv()` call at all. `file` must be root-relative, POSIX-separated -- matching `contracts`' own `ContractModel` convention, since this is matched against it by identity. */
+    readonly undocumentedContracts: readonly UndocumentedContractRef[];
+    /** Schema variables with no matching entry in their contract's linked documentation. `file` must be root-relative, POSIX-separated -- see `undocumentedContracts`. */
+    readonly undocumentedVariables: readonly UndocumentedVariableRef[];
+    /** Timestamp rendered into the header and used for expiry/days-remaining math. */
+    readonly generatedAt: Date;
+    /** Content already at `docs.location`, if any -- used only for the "changes since last report" summary. */
+    readonly previousContent: string | undefined;
+}
+/**
+ * Parses `expiresAt` as a real date.
+ *
+ * @remarks
+ * Malformed strings are silently ignored (return `undefined`) rather than throwing -- same
+ * "warn/skip, never guess" policy as the rest of the generator. Exported so `live-expirations.ts`
+ * can validate live override values against the exact same rule used for static `expiresAt`.
+ */
+export declare function parseIsoDate(value: string): Date | undefined;
+/** The minimal shape {@link computeExpiringEntries} needs -- structural, not pinned to `DiscoveredContract`, so the exact same rule serves both `LinkResult`'s absolute-path contracts (`generate-documentation.ts`'s `documentation.expiringSoon`, Stable tier) and `ContractModel`'s root-relative ones, whichever a caller already has on hand. */
+interface ExpiryBearingContract {
+    readonly file: string;
+    readonly exportName: string;
+    readonly expiresAt: string | undefined;
+    readonly variables: readonly {
+        readonly key: string;
+        readonly expiresAt: string | undefined;
+    }[];
+}
+/**
+ * Computes every contract- or variable-level `expiresAt` within `expiringWithinDays` of `now`, sorted soonest-first.
+ */
+export declare function computeExpiringEntries(contracts: readonly ExpiryBearingContract[], expiringWithinDays: number, now: Date): ExpiringEntry[];
+/**
+ * Same data `renderCatalog()` renders to Markdown for one variable, reshaped for JSON/
+ * programmatic consumers instead of prose.
+ *
+ * @see `ContractModelVariable` (`contract-model.ts`) -- this same declared variable's canonical
+ * starting point. Plain reference, not `{@link}`: this type is intentionally not part of the
+ * public surface (see `typedoc.json`'s `intentionallyNotExported`).
+ */
+interface CatalogVariable extends EnvGovernanceFields {
+    readonly description: string | undefined;
+    readonly refreshInstructions: string | undefined;
+    readonly setupInstructions: string | undefined;
+    readonly required: boolean | undefined;
+    readonly hasDefault: boolean;
+    readonly hasProcessor: boolean;
+    readonly processorReturnType: string | undefined;
+    readonly hasValidator: boolean;
+    readonly documented: boolean;
+    /** The variable's declared validation context, if any -- see ADR 0022. Participation data, not documentation: describes when `validateEnv()` processes this variable, not who may access it or what a bundler includes. */
+    readonly context: string | undefined;
+    /** The `evidence` sub-object from this variable's linked documentation -- re-verified every run, unlike every declared-only field above. See ADR 0037. */
+    readonly evidence: DiscoveredVariableEvidence | undefined;
+}
+export interface CatalogContract extends EnvGovernanceFields {
+    readonly file: string;
+    readonly exportName: string;
+    readonly contractName: string;
+    readonly active: boolean;
+    readonly documented: boolean;
+    readonly category: string | undefined;
+    readonly exclusiveGroup: string | undefined;
+    /** Keyed by variable name -- unique within one contract (a schema
+     *  object-literal property name), unlike `contractName` at the top level. */
+    readonly variables: Readonly<Record<string, CatalogVariable>>;
+}
+/**
+ * Same data `renderCatalog()` renders to Markdown, reshaped for JSON/
+ * programmatic consumers instead of prose. See `GenerateDocumentationResult.catalog`.
+ */
+export declare function buildCatalog(contracts: readonly ContractModelContract[]): CatalogContract[];
+/** Every variable key that appeared as a catalog heading in a previously-generated docs file. Exported for testing. */
+export declare function extractPreviouslyDocumentedKeys(previousContent: string): Set<string>;
+/**
+ * Every variable key that was documented under an *active* contract in a
+ * previously-generated docs file -- walks the same `- Active: yes/no`
+ * marker `renderCatalog` always emits immediately after each `## <contract>`
+ * heading, so a key already inactive last time (a permanently-dormant
+ * contract, e.g. behind an unused feature flag) is excluded even though it
+ * still appears as a `### \`KEY\`` heading. Exported for testing.
+ */
+export declare function extractPreviouslyActiveKeys(previousContent: string): Set<string>;
+/** Every number the security review reports, as structured data instead of only rendered Markdown text. */
+export interface SecurityReviewCounters {
+    readonly totalContracts: number;
+    readonly totalVariableDeclarations: number;
+    readonly activeVariableDeclarations: number;
+    readonly uniqueVariableNames: number;
+    readonly expiresAtSetCount: number;
+    readonly expiredCount: number;
+    readonly expiringSoonCount: number;
+    readonly requiredCount: number;
+    readonly refreshInstructionsCount: number;
+    readonly noOwnerCount: number;
+    readonly duplicateVariableNameCount: number;
+    readonly undocumentedContractCount: number;
+    readonly undocumentedVariableCount: number;
+}
+/**
+ * Computes every number `renderSecurityReview()` reports, as real data.
+ *
+ * @remarks
+ * Previously this arithmetic lived entirely inside the renderer as closure
+ * locals that only ever became interpolated Markdown text -- no exported
+ * type backed any of it, so nothing downstream (the `--json` envelope, a CI
+ * gate, a future Finding Model adapter) could consume it as data. Extracted
+ * so it can be reused wherever these facts are needed, not just prose.
+ */
+export declare function computeSecurityReviewCounters(contracts: readonly ContractModelContract[], expiringWithinDays: number, now: Date, undocumentedContractCount: number, undocumentedVariableCount: number): SecurityReviewCounters;
+/**
+ * Renders the full docs artifact: header + change summary + table of
+ * contents, then the comprehensive catalog, ownership matrix (if used),
+ * dependency graph, lifecycle report, and a security review.
+ *
+ * @remarks
+ * Documents everything discovered, active or not, same scope as the catalog always
+ * had. Fully regenerated every run -- unlike `.env.example`, nothing here is
+ * meant to be hand-edited, so there's no "never overwrite" behavior.
+ *
+ * `contracts` is `ContractModel`'s own shape (`file` root-relative and
+ * POSIX-separated already, per that model's convention) -- there is no
+ * separate `root` parameter to resolve against, unlike this function's
+ * pre-ADR-0038 signature.
+ */
+export declare function renderDocs(contracts: readonly ContractModelContract[], options: RenderDocsOptions): string;
+/**
+ * Normalizes every wall-clock-relative substring `renderDocs()` can produce
+ * -- not just the single `_Generated ..._` timestamp line, but also the
+ * lifecycle report's `(**Xd remaining**)`/`(**expired Xd ago**)` annotations
+ * and the security review's "Already expired"/"Expiring within N days"
+ * counts -- so two renders of the *same* input, taken on different days,
+ * compare equal. `check-artifacts.ts`'s drift comparison and the examples
+ * golden-file test harness (`test/support/example-runner.ts`) both need
+ * exactly this, not just the timestamp line alone: any contract with a near-term
+ * `expiresAt` renders day-relative text that would otherwise make `--check`
+ * (or a golden-file comparison) report false drift purely because real time
+ * passed between generation and comparison.
+ */
+export declare function normalizeDocsForComparison(content: string): string;
+export {};
+//# sourceMappingURL=docs.d.ts.map