@maverickcer/env-cap 0.2.0

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

@@ -0,0 +1,215 @@
+import type { DiscoveredSchemaVariable, DiscoveredVariableEvidence, ParseWarning } from "./parse.js";
+import type { EnvGovernanceFields } from "./governance-fields.js";
+import type { ImportResolutionContext } from "./resolution/resolve-import.js";
+import type { PackageOrigin } from "./resolution/resolve-package-schema.js";
+import type { SourcePosition } from "./source-position.js";
+/** One schema variable, merged with its linked `documentEnv()` documentation (if any). */
+/**
+ * One schema variable merged with its linked `documentEnv()` documentation. Its
+ * governance fields (`owner` .. `metadata`) are {@link EnvGovernanceFields} --
+ * each an individual-variable override of the contract's own value, from the
+ * linked `documentEnv()` call's matching `variables` entry, or `undefined`.
+ */
+export interface DiscoveredVariable extends DiscoveredSchemaVariable, EnvGovernanceFields {
+    /** From the linked `documentEnv()` call's matching `variables` entry, if any. */
+    readonly description: string | undefined;
+    /** From the linked `documentEnv()` call's matching `variables` entry, if any. */
+    readonly refreshInstructions: string | undefined;
+    /** From the linked `documentEnv()` call's matching `variables` entry, if any. */
+    readonly setupInstructions: string | undefined;
+    /** From the linked `documentEnv()` call's matching `variables` entry, if any. */
+    readonly required: boolean | undefined;
+    /** From the linked `documentEnv()` call's matching `variables` entry, if any. */
+    readonly deprecated: boolean | undefined;
+    /** From the linked `documentEnv()` call's matching `variables` entry, if any. */
+    readonly deprecatedReason: string | undefined;
+    /** From the linked `documentEnv()` call's matching `variables` entry, if any. */
+    readonly removeBy: string | undefined;
+    /** From the linked `documentEnv()` call's matching `variables` entry, if any -- the previous variable name this one renames, if this declaration is the result of a rename. */
+    readonly renamedFrom: string | undefined;
+    /** The linked `documentEnv()` entry's `evidence` sub-object -- the re-verified-every-run half of this variable's documentation, deliberately not flattened in alongside the declared-only fields above. See {@link runtime.VariableEvidenceDocs} and ADR 0037. */
+    readonly evidence: DiscoveredVariableEvidence | undefined;
+    /** Whether this specific key had a matching entry in the linked `documentEnv()` call, if any. */
+    readonly documented: boolean;
+}
+/** One `createEnv()` contract, merged with its linked `documentEnv()` documentation (if any). Its governance fields (`owner` .. `metadata`) are {@link EnvGovernanceFields} -- contract-level defaults that individual variables may override. */
+export interface DiscoveredContract extends EnvGovernanceFields {
+    /** Absolute path of the file declaring the `createEnv()` call. */
+    readonly file: string;
+    /** The binding name the `createEnv()` result is exported as. */
+    readonly exportName: string;
+    /** Resolved display name: linked `documentEnv()`'s `name`, else `createEnv()`'s own `name` option, else `exportName`. */
+    readonly contractName: string;
+    /** From the linked `documentEnv()`'s `active` option. Defaults to `true` when omitted or undocumented. */
+    readonly active: boolean;
+    /** From the linked `documentEnv()` call, if any. */
+    readonly category: string | undefined;
+    /** From the linked `documentEnv()` call, if any -- see {@link runtime.ContractDocs.exclusiveGroup}. */
+    readonly exclusiveGroup: string | undefined;
+    /** From the linked `documentEnv()` call, if any. */
+    readonly deprecated: boolean | undefined;
+    /** From the linked `documentEnv()` call, if any. */
+    readonly deprecatedReason: string | undefined;
+    /** Every variable declared in the schema, merged with its linked documentation. */
+    readonly variables: readonly DiscoveredVariable[];
+    /** Whether *any* `documentEnv()` call is linked to this contract at all. */
+    readonly documented: boolean;
+    /** Set when this contract was discovered via an allow-listed package's
+     *  declared schema entry point rather than local discovery -- the bare
+     *  package name `renderManifest()` must import from instead of computing a
+     *  relative path to the (analysis-only) resolved file. See ADR 0014. */
+    readonly packageOrigin: PackageOrigin | undefined;
+    /** Where this contract's `createEnv(...)` call is declared. Always present -- every discovered contract has one, by definition. See ADR 0036. */
+    readonly declaration: SourcePosition;
+    /** Where this contract's `documentEnv(...)` call is declared, if one exists. Undefined for a contract that's never been documented. See ADR 0036. */
+    readonly documentation: SourcePosition | undefined;
+}
+/** A `documentEnv()` call that could not be statically linked back to a `createEnv()` schema. */
+export interface UnresolvedLink {
+    /** Absolute path of the file containing the unlinkable call. */
+    readonly file: string;
+    /** Human-readable explanation of why the link couldn't be resolved. */
+    readonly reason: string;
+}
+/** The full result of {@link linkFiles}: every linked contract, plus every category of thing that didn't link cleanly. */
+export interface LinkResult {
+    /** Every `createEnv()` contract found, merged with its documentation. */
+    readonly contracts: readonly DiscoveredContract[];
+    /** Parse-time warnings collected across every analyzed file. */
+    readonly warnings: readonly ParseWarning[];
+    /** `documentEnv()` calls that couldn't be statically linked to a schema. */
+    readonly unresolvedLinks: readonly UnresolvedLink[];
+    /** Contracts with no linked `documentEnv()` call at all. */
+    readonly undocumentedContracts: readonly {
+        /** Absolute path of the file declaring the contract. */
+        readonly file: string;
+        /** The contract's exported binding name. */
+        readonly exportName: string;
+    }[];
+    /** Schema variables with no matching entry in their contract's linked documentation. */
+    readonly undocumentedVariables: readonly {
+        /** Absolute path of the file declaring the contract. */
+        readonly file: string;
+        /** The contract's exported binding name. */
+        readonly exportName: string;
+        /** The undocumented environment variable name. */
+        readonly key: string;
+    }[];
+    /** Documented variable entries with no matching schema variable (the schema key was removed or renamed). */
+    readonly staleDocEntries: readonly {
+        /** Absolute path of the file declaring the contract. */
+        readonly file: string;
+        /** The contract's exported binding name. */
+        readonly exportName: string;
+        /** The stale documented variable name. */
+        readonly key: string;
+    }[];
+}
+/**
+ * Parses every discovered file, then resolves and links `createEnv`/
+ * `documentEnv` calls into the merged, docs-enriched contract shape the rest
+ * of the generator (`compatibility.ts`, `exclusive-group.ts`, `manifest.ts`,
+ * `docs.ts`, `env-example.ts`) consumes.
+ *
+ * @remarks
+ * Cross-file linking is deliberately narrow (see `resolveImportSpecifier`):
+ * a `documentEnv()` call's schema reference resolves either to a `const` in
+ * its own file, to a directly-imported named export of another file's
+ * `const`, or (since ADR 0014) to an allow-listed package's declared schema
+ * entry point. Anything else -- a re-export barrel, a namespace import, an
+ * unlisted bare package specifier -- becomes an `unresolvedLinks` entry
+ * rather than a throw or a guess, exactly like every other static-analysis
+ * boundary in this codebase.
+ *
+ * `packageOrigins` (from `resolveAllowlistedPackages()`) tags any discovered
+ * contract whose `file` matches a package-resolved path with that package's
+ * origin -- purely a lookup; `discoveredFiles` must already include those
+ * files (merged in by the caller via `mergeLocalAndPackageFiles()`).
+ *
+ * @param context - See `ImportResolutionContext`; drives how a resolved import specifier maps back to a file on disk.
+ */
+export declare function linkFiles(discoveredFiles: readonly string[], readFile: (filePath: string) => Promise<string>, context: ImportResolutionContext, packageOrigins?: ReadonlyMap<string, PackageOrigin>): Promise<LinkResult>;
+/** Root-relative projection of a {@link DiscoveredContract}, as returned by {@link generateEnvManifest}/{@link generateDocumentation}. */
+export interface DiscoveredContractSummary {
+    /** Root-relative, POSIX-separated file path. */
+    readonly file: string;
+    /** The binding name the `createEnv()` result is exported as. */
+    readonly exportName: string;
+    /** Resolved display name (see {@link DiscoveredContract.contractName}). */
+    readonly contractName: string;
+    /** Number of variables declared in this contract's schema. */
+    readonly variableCount: number;
+    /** Whether this contract was included in the generated manifest (`active` defaults to true). */
+    readonly active: boolean;
+    /** Whether a `documentEnv()` call is linked to this contract. */
+    readonly documented: boolean;
+}
+/**
+ * Projects a {@link DiscoveredContract} (absolute `file`) into the root-relative
+ * summary shape returned by {@link generateEnvManifest}/{@link generateDocumentation}.
+ *
+ * @remarks
+ * Pulled out here, rather than duplicated in both, since it's a pure
+ * projection with no manifest- or docs-specific behavior.
+ */
+export declare function summarizeContract(contract: DiscoveredContract, root: string): DiscoveredContractSummary;
+/**
+ * A variable's owner, falling back to its contract's default when the
+ * variable itself doesn't set one.
+ *
+ * @remarks
+ * The one place this resolution rule should live -- see ADR 0028. Every
+ * caller that needs "who owns this variable" (the docs Catalog/ownership
+ * matrix/security review, and, as of ADR 0028, the usage report's
+ * variable-level ownership findings) must go through this, not
+ * `variable.owner` or `contract.owner` alone, so two call sites can never
+ * again disagree about who owns a variable the way `docs.ts` and
+ * `usage-report.ts` once did.
+ *
+ * Structurally typed (not pinned to `DiscoveredContract`/`DiscoveredVariable`)
+ * so the same one resolution rule also serves `ContractModelContract`/
+ * `ContractModelVariable` (`contract-model.ts`) -- both shapes carry the same
+ * field, and this rule must never have two independent implementations.
+ */
+export declare function effectiveOwner(contract: {
+    readonly owner: string | undefined;
+}, variable: {
+    readonly owner: string | undefined;
+}): string | undefined;
+/** A variable's sensitivity, falling back to its contract's default -- see {@link effectiveOwner}. */
+export declare function effectiveSensitivity(contract: {
+    readonly sensitivity: string | undefined;
+}, variable: {
+    readonly sensitivity: string | undefined;
+}): string | undefined;
+/** A variable's purpose, falling back to its contract's default -- see {@link effectiveOwner}. */
+export declare function effectivePurpose(contract: {
+    readonly purpose: string | undefined;
+}, variable: {
+    readonly purpose: string | undefined;
+}): string | undefined;
+/** A variable's legal basis, falling back to its contract's default -- see {@link effectiveOwner}. */
+export declare function effectiveLegalBasis(contract: {
+    readonly legalBasis: string | undefined;
+}, variable: {
+    readonly legalBasis: string | undefined;
+}): string | undefined;
+/** A variable's retention policy, falling back to its contract's default -- see {@link effectiveOwner}. */
+export declare function effectiveRetention(contract: {
+    readonly retention: string | undefined;
+}, variable: {
+    readonly retention: string | undefined;
+}): string | undefined;
+/** A variable's data residency, falling back to its contract's default -- see {@link effectiveOwner}. */
+export declare function effectiveDataResidency(contract: {
+    readonly dataResidency: string | readonly string[] | undefined;
+}, variable: {
+    readonly dataResidency: string | readonly string[] | undefined;
+}): string | readonly string[] | undefined;
+/** A variable's audit-required assertion, falling back to its contract's default -- see {@link effectiveOwner}. */
+export declare function effectiveAuditRequired(contract: {
+    readonly auditRequired: boolean | undefined;
+}, variable: {
+    readonly auditRequired: boolean | undefined;
+}): boolean | undefined;
+//# sourceMappingURL=link.d.ts.map

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

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

package/dist/.dts/build/literal-eval.d.ts

@@ -0,0 +1,23 @@
+import ts from "typescript";
+/**
+ * The result of a literal evaluation: either a real JS value, or `{ ok: false }` when the AST
+ * expression wasn't a literal (or contained a non-literal element/property).
+ */
+export type LiteralEvalResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+};
+/**
+ * Structurally evaluates a *literal* AST expression (strings, numbers, booleans, null, arrays,
+ * and object literals of the same) into a real JS value -- without ever executing code.
+ *
+ * @remarks
+ * Anything that isn't a literal (identifiers, calls, imports, template expressions with
+ * interpolation) resolves to `{ ok: false }` rather than being guessed at.
+ */
+export declare function evaluateLiteral(node: ts.Expression): LiteralEvalResult;
+/** Reads a property name statically (identifier, string literal, or numeric literal) -- a computed key (e.g. `[expr]`) resolves to `undefined` rather than being guessed at. */
+export declare function getStaticPropertyName(name: ts.PropertyName): string | undefined;
+//# sourceMappingURL=literal-eval.d.ts.map

package/dist/.dts/build/literal-eval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"literal-eval.d.ts","sourceRoot":"","sources":["../../../src/build/literal-eval.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAA;AAE3B;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAA;AAE5E;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,GAAG,iBAAiB,CA4CtE;AAED,gLAAgL;AAChL,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,GAAG,MAAM,GAAG,SAAS,CAK/E"}

package/dist/.dts/build/live-expirations.d.ts

@@ -0,0 +1,47 @@
+import type { DiscoveredContract } from "./link.js";
+/**
+ * Supplies expiration metadata from a live source (a secrets manager, an
+ * internal inventory API, ...) as a post-discovery override -- the one
+ * sanctioned escape hatch from static-only `expiresAt`.
+ *
+ * @remarks
+ * Invoked exactly once per generation run, from the orchestration layer, after AST discovery/
+ * linking completes and before documentation is rendered. Never invoked
+ * during AST parsing or runtime validation -- see ADR 0012 for why a
+ * function embedded in a schema file itself was rejected instead.
+ */
+export type LiveExpirationDates = (variableNames: readonly string[]) => Promise<Readonly<Record<string, string>>>;
+/**
+ * Every unique variable key across every linked contract's `variables`.
+ * Contract-level `expiresAt` is out of scope for override -- the callback is
+ * keyed by variable name, not contract name.
+ */
+export declare function collectVariableNames(contracts: readonly DiscoveredContract[]): string[];
+/**
+ * Applies `overrides` onto a fresh copy of `contracts` -- every contract and
+ * every variable (and their nested `metadata`/`extra` records) is rebuilt
+ * into a new object, never the original reference, so the returned structure
+ * shares no mutable object identity with `contracts` at any depth.
+ *
+ * @remarks
+ * A key absent from `overrides`, or present but not a `parseIsoDate`-parseable
+ * ISO-8601 string, leaves that variable's static `expiresAt` untouched --
+ * same "warn/skip, never guess" policy the rest of the generator uses for
+ * malformed data. Contract-level `expiresAt` is never touched; only
+ * variable-level `expiresAt` is in scope for override.
+ */
+export declare function applyLiveExpirationOverrides(contracts: readonly DiscoveredContract[], overrides: Readonly<Record<string, string>>): readonly DiscoveredContract[];
+/**
+ * Orchestration entry point -- the only place `liveExpirationDates` is ever invoked.
+ *
+ * @remarks
+ * No-ops (returns the exact same array reference, zero invocations)
+ * when `liveExpirationDates` is undefined, which is what guarantees "omitted ->
+ * behavior unchanged." Otherwise collects the unique discovered variable
+ * names, invokes the callback exactly once, applies the result, and
+ * deep-freezes the returned structure so it can never be mutated into
+ * affecting `contracts` (used elsewhere, e.g. by the manifest/usage passes in
+ * the same {@link generateEnvArtifacts} run) or anything else downstream.
+ */
+export declare function resolveLiveExpirationDates(contracts: readonly DiscoveredContract[], liveExpirationDates: LiveExpirationDates | undefined): Promise<readonly DiscoveredContract[]>;
+//# sourceMappingURL=live-expirations.d.ts.map

package/dist/.dts/build/live-expirations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-expirations.d.ts","sourceRoot":"","sources":["../../../src/build/live-expirations.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAsB,MAAM,WAAW,CAAA;AAEvE;;;;;;;;;;GAUG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAChC,aAAa,EAAE,SAAS,MAAM,EAAE,KAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;AAE9C;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,SAAS,kBAAkB,EAAE,GAAG,MAAM,EAAE,CAMvF;AA2BD;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAC1C,SAAS,kBAAkB,EAAE,CAM/B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,0BAA0B,CAC9C,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,mBAAmB,EAAE,mBAAmB,GAAG,SAAS,GACnD,OAAO,CAAC,SAAS,kBAAkB,EAAE,CAAC,CAIxC"}

package/dist/.dts/build/manifest-snapshot.d.ts

@@ -0,0 +1,229 @@
+import type { DiscoveredContract } from "./link.js";
+import type { DiscoveredClassification, ParseWarning } from "./parse.js";
+import type { DynamicAccessAssertion, SourcePosition } from "./source-position.js";
+/**
+ * The manifest's own `.ts` output is deliberately metadata-free (imports +
+ * an array, see `manifest.ts`'s docstring) -- there is nothing in it for a
+ * later `generateEnvManifest()` run to read back and diff against. This
+ * module is the persisted, committed sidecar that makes "what changed in
+ * `documentEnv()` since last time" answerable at all. See ADR 0021.
+ */
+/** 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 `src/cli/json.ts`'s `JSON_SCHEMA_VERSION` already documents;
+ *  this format is meant to stay backwards-compatible across ordinary
+ *  releases. */
+export declare const MANIFEST_SNAPSHOT_SCHEMA_VERSION = 2;
+export interface ManifestSnapshotVariable {
+    readonly key: string;
+    readonly description: string | undefined;
+    readonly owner: string | undefined;
+    readonly classification: DiscoveredClassification | undefined;
+    readonly expiresAt: string | undefined;
+    readonly refreshInstructions: string | undefined;
+    readonly setupInstructions: string | undefined;
+    readonly required: boolean | undefined;
+    readonly deprecated: boolean | undefined;
+    readonly deprecatedReason: string | undefined;
+    readonly removeBy: string | undefined;
+    readonly renamedFrom: string | undefined;
+    readonly purpose: string | undefined;
+    readonly legalBasis: string | undefined;
+    readonly retentionPolicy: string | undefined;
+    readonly dataResidency: string | readonly string[] | undefined;
+    readonly auditRequired: boolean | undefined;
+    readonly metadata: Readonly<Record<string, unknown>> | undefined;
+    readonly documented: boolean;
+    /**
+     * One entry per {@link runtime.VariableDocs.dynamicAccess} citation whose
+     * cited file existed at snapshot-build time, each carrying a SHA-256 hex
+     * digest of that file's full content at that moment -- the committed
+     * baseline a later run's citation is compared against to tell "fresh" from
+     * "stale" (ADR 0037). A citation whose file doesn't exist at build time is
+     * simply omitted here, not recorded as an error -- `computeManifestChanges()`'s
+     * own live existence check is what reports a missing file, every run,
+     * independent of this stored baseline. `buildManifestSnapshot()` always
+     * populates this (as `[]` at minimum); typed `| undefined` because it's
+     * purely additive (no `MANIFEST_SNAPSHOT_SCHEMA_VERSION` bump), so a real
+     * snapshot committed before this field existed reads back as "ok" while
+     * genuinely lacking the key -- every reader must treat it as optional.
+     */
+    readonly dynamicAccessSnapshots: readonly (SourcePosition & {
+        readonly acknowledgedContentHash: string;
+    })[] | undefined;
+}
+export interface ManifestSnapshotContract {
+    /** 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 owner: string | undefined;
+    readonly classification: DiscoveredClassification | undefined;
+    readonly expiresAt: string | undefined;
+    readonly deprecated: boolean | undefined;
+    readonly deprecatedReason: string | undefined;
+    readonly purpose: string | undefined;
+    readonly legalBasis: string | undefined;
+    readonly retentionPolicy: string | undefined;
+    readonly dataResidency: string | readonly string[] | undefined;
+    readonly auditRequired: boolean | undefined;
+    readonly metadata: Readonly<Record<string, unknown>> | undefined;
+    readonly variables: readonly ManifestSnapshotVariable[];
+}
+export interface ManifestSnapshot {
+    readonly schemaVersion: typeof MANIFEST_SNAPSHOT_SCHEMA_VERSION;
+    readonly contracts: readonly ManifestSnapshotContract[];
+}
+/**
+ * Sorted deterministically (by file, then exportName, then variable key) so
+ * `JSON.stringify` output is stable and diffs cleanly in PRs. Scoped to
+ * **active** contracts only, matching `renderManifest()`'s own scope -- a
+ * contract flipping to `active: false` disappears from `manifest.ts` itself,
+ * so it disappears from this snapshot too.
+ */
+export declare function buildManifestSnapshot(activeContracts: readonly DiscoveredContract[], root: string, readFile: (filePath: string) => Promise<string>): Promise<ManifestSnapshot>;
+/** Derives the sidecar snapshot path from a manifest's own output path (e.g. `src/generated/env.manifest.ts` -> `src/generated/env.manifest.snapshot.json`). */
+export declare function manifestSnapshotPath(manifestOutputPath: string): string;
+/**
+ * Distinguishes *why* there's no usable previous snapshot, rather than
+ * collapsing every case into a bare `undefined`. A missing file is the
+ * normal, silent, expected first-run case. An unparseable file or a
+ * `schemaVersion` this build doesn't recognize are both real, diagnosable
+ * problems -- `computeManifestChanges()` below surfaces those two (never
+ * `"missing"`) as a `ParseWarning` instead of silently re-baselining.
+ */
+export type ManifestSnapshotReadResult = {
+    readonly status: "missing";
+} | {
+    readonly status: "invalid-json";
+    readonly detail: string;
+} | {
+    readonly status: "unsupported-version";
+    readonly foundVersion: unknown;
+} | {
+    readonly status: "ok";
+    readonly snapshot: ManifestSnapshot;
+};
+export declare function readManifestSnapshot(snapshotPath: string): Promise<ManifestSnapshotReadResult>;
+export declare function writeManifestSnapshot(snapshotPath: string, snapshot: ManifestSnapshot): Promise<void>;
+/** One field's before/after value in a {@link ManifestContractUpdate} or {@link ManifestVariableUpdate}. */
+export interface ManifestFieldChange {
+    /** The changed field's name (dotted, e.g. `metadata.runbook`, for a per-key record change). */
+    readonly field: string;
+    /** The value from the previous snapshot, or `undefined` if the field was unset. */
+    readonly previous: string | undefined;
+    /** The value in the current run, or `undefined` if the field is now unset. */
+    readonly current: string | undefined;
+}
+/** Identifies one contract for {@link ManifestChangeReport} purposes. */
+export interface ManifestContractRef {
+    /** Stable identity: `${file}#${exportName}`. */
+    readonly identity: string;
+    /** Root-relative, POSIX-separated file path. */
+    readonly file: string;
+    /** The binding name the `createEnv()` result is exported as. */
+    readonly exportName: string;
+    /** Resolved display name (see {@link DiscoveredContract.contractName}). */
+    readonly contractName: string;
+}
+/** Identifies one variable for {@link ManifestChangeReport} purposes. */
+export interface ManifestVariableRef {
+    /** Stable identity: `${contractIdentity}#${key}`. */
+    readonly identity: string;
+    /** The owning contract's {@link ManifestContractRef.identity}. */
+    readonly contractIdentity: string;
+    /** Root-relative, POSIX-separated file path of the owning contract. */
+    readonly file: string;
+    /** The owning contract's exported binding name. */
+    readonly exportName: string;
+    /** The owning contract's resolved display name. */
+    readonly contractName: string;
+    /** The environment variable name. */
+    readonly key: string;
+}
+/** A contract present in both snapshots, with at least one changed field. */
+export interface ManifestContractUpdate extends ManifestContractRef {
+    /** Every field that changed between the previous and current snapshot. */
+    readonly changes: readonly ManifestFieldChange[];
+}
+/** A variable present in both snapshots, with at least one changed field. */
+export interface ManifestVariableUpdate extends ManifestVariableRef {
+    /** Every field that changed between the previous and current snapshot. */
+    readonly changes: readonly ManifestFieldChange[];
+}
+/** The result of diffing two manifest snapshots -- see `result.manifest.changes` (ADR 0021). */
+export interface ManifestChangeReport {
+    /** Contracts present now but not in the previous snapshot. */
+    readonly addedContracts: readonly ManifestContractRef[];
+    /** Contracts present in the previous snapshot but not now. */
+    readonly removedContracts: readonly ManifestContractRef[];
+    /** Variables present now but not in the previous snapshot. */
+    readonly addedVariables: readonly ManifestVariableRef[];
+    /** Variables present in the previous snapshot but not now. */
+    readonly removedVariables: readonly ManifestVariableRef[];
+    /** Contracts present in both snapshots with at least one changed field. */
+    readonly updatedContracts: readonly ManifestContractUpdate[];
+    /** Variables present in both snapshots with at least one changed field. */
+    readonly updatedVariables: readonly ManifestVariableUpdate[];
+}
+/**
+ * Pure. `previous === undefined` (no snapshot last time, for any reason --
+ * see `ManifestSnapshotReadResult`) reports everything in `current` as
+ * added, nothing as removed/updated.
+ */
+export declare function diffManifestSnapshots(previous: ManifestSnapshot | undefined, current: ManifestSnapshot): ManifestChangeReport;
+/** Stable key `dynamicAccessAcknowledgments` (below) 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
+ * snapshot's committed baseline, keyed by `${file}#${exportName}#${key}`
+ * (matching `ManifestVariableRef.identity`'s own scheme). 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 every other
+ * committed-baseline field in this module already follows. See ADR 0037.
+ */
+export declare function computeDynamicAccessAcknowledgments(activeContracts: readonly DiscoveredContract[], previous: ManifestSnapshot | 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 `"dynamic-access-citation-stale"`/`"dynamic-access-citation-missing"` 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 `dynamicAccessAcknowledgments` down to just the citations that
+ * need attention -- every `"stale"`/`"missing"` assertion, enriched with the
+ * owning contract's display name (the acknowledgments map itself only keys
+ * by identity, not a renderable name). `"fresh"` assertions are silently
+ * omitted -- nothing to report about a citation that's still trustworthy.
+ */
+export declare function findDynamicAccessCitationProblems(activeContracts: readonly DiscoveredContract[], root: string, acknowledgments: ReadonlyMap<string, readonly DynamicAccessAssertion[]>): readonly DynamicAccessCitationProblem[];
+export interface ManifestChangesComputation {
+    readonly report: ManifestChangeReport;
+    readonly snapshot: ManifestSnapshot;
+    /** Set only when the previous snapshot existed but was unusable (corrupt JSON or an unrecognized `schemaVersion`) -- never set for the ordinary "no snapshot yet" first-run case. */
+    readonly readWarning: ParseWarning | undefined;
+    /** Every current `dynamicAccess` citation's freshness, keyed by `${file}#${exportName}#${key}` -- see `computeDynamicAccessAcknowledgments()`. See ADR 0037. */
+    readonly dynamicAccessAcknowledgments: ReadonlyMap<string, readonly DynamicAccessAssertion[]>;
+    /** Every citation that isn't `"fresh"` -- see `findDynamicAccessCitationProblems()`. Derived from `dynamicAccessAcknowledgments` above for convenience; a caller could equally recompute it. */
+    readonly dynamicAccessCitationProblems: readonly DynamicAccessCitationProblem[];
+}
+/**
+ * The one I/O-performing helper both `generateEnvManifest()` and
+ * `generate-env-artifacts.ts`'s `computeArtifacts()` share: builds the
+ * current snapshot, reads the previous one, diffs. Writing the new snapshot
+ * stays a separate, explicit step on the real write path -- this never
+ * writes anything itself, so it's safe to call from a read-only compute too.
+ */
+export declare function computeManifestChanges(root: string, manifestOutputPath: string, activeContracts: readonly DiscoveredContract[], readFile: (filePath: string) => Promise<string>): Promise<ManifestChangesComputation>;
+//# sourceMappingURL=manifest-snapshot.d.ts.map

package/dist/.dts/build/manifest-snapshot.d.ts.map

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

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

@@ -0,0 +1,31 @@
+import type { DiscoveredContract } from "./link.js";
+/**
+ * Every validation context declared by any variable in an *active* contract
+ * in `contracts` (a variable belonging to a contract documented `active:
+ * false` never contributes -- same exclusion the `manifest` array itself
+ * already applies), sorted and deduplicated. What {@link renderManifest}
+ * surfaces as the generated `activeContexts` export. Exported for reuse by
+ * anything that needs the same computation (currently just `renderManifest`
+ * itself).
+ */
+export declare function discoverValidationContexts(contracts: readonly DiscoveredContract[]): readonly string[];
+/**
+ * Renders the deterministic manifest source: sorted imports (aliased on name
+ * collision) plus a `contracts` array, in the exact banner format schema
+ * authors will recognize as generated. No timestamps, no randomness -- same
+ * input files always produce byte-identical output.
+ *
+ * @remarks
+ * When at least one discovered variable declares a `context` (ADR 0022),
+ * this also emits `activeContexts` -- every validation context found across
+ * `contracts`, as a plain array named to match {@link runtime.validateEnvOptions}'s
+ * own `activeContexts` field -- so application code can import it alongside
+ * `manifest` and pass it straight through: `validateEnv({ manifest, values, activeContexts })`.
+ * It's every context this manifest has, meant as a starting point to narrow
+ * per process/deployment, not a pre-scoped default -- see the README's
+ * "Validation contexts" section. Omitted entirely (not even an empty array)
+ * when no variable declares a `context` at all, so generated output for
+ * projects that don't use this feature is untouched.
+ */
+export declare function renderManifest(contracts: readonly DiscoveredContract[], outputFile: string): string;
+//# sourceMappingURL=manifest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/build/manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAEnD;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,SAAS,kBAAkB,EAAE,GACvC,SAAS,MAAM,EAAE,CASnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,UAAU,EAAE,MAAM,GACjB,MAAM,CA8DR"}

package/dist/.dts/build/map-utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `map.get(key)` after iterating `map`'s own `.keys()` is always defined --
+ * this makes that invariant an explicit, named operation instead of a bare
+ * `!` non-null assertion at each call site, with a real error (not a
+ * silent `undefined`) if it's ever violated by a future bug.
+ */
+export declare function mustGet<K, V>(map: ReadonlyMap<K, V>, key: K): V;
+//# sourceMappingURL=map-utils.d.ts.map

package/dist/.dts/build/map-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"map-utils.d.ts","sourceRoot":"","sources":["../../../src/build/map-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAK/D"}