@maverickcer/env-cap 0.2.0

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

@@ -0,0 +1,57 @@
+import type { ContractRef } from "./evidence-reference.js";
+import type { DiscoveredContract } from "./link.js";
+/**
+ * The third of env-cap's seven canonical fact models (ADR 0024) -- every
+ * contract and variable's effective owner, plus first-class
+ * `unownedContracts`/`unownedVariables` arrays. See ADR 0028.
+ *
+ * @remarks
+ * "Unowned" previously existed only as a count (`noOwnerCount`) inside
+ * `docs.ts`'s `renderSecurityReview()` -- itemized here as real data for the
+ * first time, computed via the same `effectiveOwner()` (variable overrides
+ * contract) that ADR 0028 also fixed `usage-report.ts`'s ownership findings
+ * to use, so this model can never disagree with either of them about who
+ * owns a variable.
+ */
+/** Bump only when a reader could misinterpret the new shape -- same discipline every other canonical model's `schemaVersion` follows. */
+export declare const OWNERSHIP_MODEL_SCHEMA_VERSION = 1;
+/**
+ * One variable's effective owner (its own, falling back to the contract's).
+ *
+ * @see {@link ContractModelVariable} -- this same declared variable's canonical starting point.
+ */
+export interface OwnershipModelVariable {
+    readonly key: string;
+    /** The variable's own `owner`, falling back to the contract's -- see `effectiveOwner()`. */
+    readonly owner: string | undefined;
+}
+export interface OwnershipModelContract {
+    /** Root-relative, POSIX-separated -- matches `ContractModelContract.file`. */
+    readonly file: string;
+    readonly exportName: string;
+    readonly contractName: string;
+    /** The contract's own default owner -- not "effective" the way a variable's is, since there's no level above a contract to fall back to. */
+    readonly owner: string | undefined;
+    readonly variables: readonly OwnershipModelVariable[];
+}
+/** One contract, referenced by identity only -- see {@link ContractRef} for why no `contractName` is carried here. Resolve one from `ContractModel` when a renderer needs display text. */
+export type OwnershipModelContractRef = ContractRef;
+/** One variable, referenced by its owning contract's identity plus its own key -- see {@link ContractRef}. */
+export interface OwnershipModelVariableRef extends ContractRef {
+    readonly key: string;
+}
+export interface OwnershipModel {
+    readonly schemaVersion: typeof OWNERSHIP_MODEL_SCHEMA_VERSION;
+    readonly contracts: readonly OwnershipModelContract[];
+    /** Every contract with no `owner` set at all. */
+    readonly unownedContracts: readonly OwnershipModelContractRef[];
+    /** Every variable whose effective owner (its own, falling back to the contract's) is still `undefined`. */
+    readonly unownedVariables: readonly OwnershipModelVariableRef[];
+}
+/**
+ * Projects every discovered contract (active or not, same scope as
+ * `renderSecurityReview()`'s `noOwnerCount` this model itemizes) into the
+ * Ownership Model's versioned, JSON-serializable shape.
+ */
+export declare function buildOwnershipModel(contracts: readonly DiscoveredContract[], root: string): OwnershipModel;
+//# sourceMappingURL=ownership-model.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ownership-model.d.ts","sourceRoot":"","sources":["../../../src/build/ownership-model.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAE1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAEnD;;;;;;;;;;;;GAYG;AAEH,yIAAyI;AACzI,eAAO,MAAM,8BAA8B,IAAI,CAAA;AAE/C;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;CACnC;AAED,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,4IAA4I;IAC5I,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,QAAQ,CAAC,SAAS,EAAE,SAAS,sBAAsB,EAAE,CAAA;CACtD;AAED,2LAA2L;AAC3L,MAAM,MAAM,yBAAyB,GAAG,WAAW,CAAA;AAEnD,8GAA8G;AAC9G,MAAM,WAAW,yBAA0B,SAAQ,WAAW;IAC5D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,aAAa,EAAE,OAAO,8BAA8B,CAAA;IAC7D,QAAQ,CAAC,SAAS,EAAE,SAAS,sBAAsB,EAAE,CAAA;IACrD,iDAAiD;IACjD,QAAQ,CAAC,gBAAgB,EAAE,SAAS,yBAAyB,EAAE,CAAA;IAC/D,2GAA2G;IAC3G,QAAQ,CAAC,gBAAgB,EAAE,SAAS,yBAAyB,EAAE,CAAA;CAChE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,IAAI,EAAE,MAAM,GACX,cAAc,CAmChB"}

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

@@ -0,0 +1,199 @@
+import ts from "typescript";
+import type { EnvGovernanceFields } from "./governance-fields.js";
+import type { SourcePosition } from "./source-position.js";
+/** A recoverable issue found while statically parsing or linking one schema file -- never fatal, always surfaced to the caller as data. */
+export interface ParseWarning {
+    /** Absolute path of the file the warning applies to. */
+    readonly file: string;
+    /** Human-readable explanation of what was skipped and why. */
+    readonly message: string;
+}
+/**
+ * How a `createEnv`/`documentEnv` call's first argument resolves, before any
+ * cross-file linking is attempted (that's `link.ts`'s job, not this file's --
+ * this module only ever looks at one file's own AST).
+ */
+export type SchemaRef = {
+    /** Discriminant: the schema argument is an inline object literal. */
+    readonly kind: "literal";
+    /** The object literal AST node itself. */
+    readonly node: ts.ObjectLiteralExpression;
+} | {
+    /** Discriminant: the schema argument is a bare identifier referencing a local `const`. */
+    readonly kind: "identifier";
+    /** The referenced identifier's name, not yet resolved to a declaration. */
+    readonly name: string;
+} | {
+    /** Discriminant: the schema argument isn't statically resolvable (not a literal or identifier). */
+    readonly kind: "unresolvable";
+};
+/** One `createEnv(...)` call site, as found by {@link parseSchemaFile}, before cross-file linking. */
+interface RawCreateEnvCall {
+    /** The binding name the call result is assigned to (must be exported to be usable -- see {@link parseSchemaFile}). */
+    readonly exportName: string;
+    /** How the first (schema) argument resolves within this file. */
+    readonly schemaRef: SchemaRef;
+    /** The second (options) argument expression, if the call passes one. */
+    readonly optionsArg: ts.Expression | undefined;
+    /** The full call expression AST node. */
+    readonly node: ts.CallExpression;
+}
+/** One `documentEnv(...)` call site, as found by {@link parseSchemaFile}, before cross-file linking. */
+interface RawDocumentEnvCall {
+    /** How the first (schema) argument resolves within this file. */
+    readonly schemaRef: SchemaRef;
+    /** The second (docs) argument expression, if the call passes one. */
+    readonly docsArg: ts.Expression | undefined;
+    /** The full call expression AST node. */
+    readonly node: ts.CallExpression;
+}
+/** One named import binding, tracked only for relative specifiers (see {@link FileParseResult.imports}). */
+export interface ImportBinding {
+    /** The raw module specifier as written in the import (e.g. `"./payments.schema.js"`). */
+    readonly specifier: string;
+    /** The name as exported by the source module -- accounts for `import { real as local }`. */
+    readonly importedName: string;
+}
+/** The raw, single-file facts extracted by {@link parseSchemaFile}. */
+export interface FileParseResult {
+    /** Absolute path of the parsed file. */
+    readonly file: string;
+    /** The TypeScript AST for this file, reused by callers that need to inspect it further. */
+    readonly sourceFile: ts.SourceFile;
+    /** Top-level `const NAME = {...}` object-literal declarations, whether exported or not. */
+    readonly localConsts: ReadonlyMap<string, ts.ObjectLiteralExpression>;
+    /** Names of top-level `const` declarations that are exported (a subset of {@link localConsts}'s keys, plus non-object-literal exports). */
+    readonly exportedConstNames: ReadonlySet<string>;
+    /** Local binding name -> where it came from. Only named imports of a relative specifier are tracked (namespace/default/bare-package imports are irrelevant to schema linking). */
+    readonly imports: ReadonlyMap<string, ImportBinding>;
+    /** Every `createEnv(...)` call site found at the top level of this file. */
+    readonly createEnvCalls: readonly RawCreateEnvCall[];
+    /** Every `documentEnv(...)` call site found at the top level of this file. */
+    readonly documentEnvCalls: readonly RawDocumentEnvCall[];
+    /** Recoverable issues found while parsing this file. */
+    readonly warnings: readonly ParseWarning[];
+}
+/**
+ * Structurally parses one file's AST for everything the generator needs:
+ * `createEnv(...)`/`documentEnv(...)` call sites, the local `const`
+ * declarations and imports needed to resolve an identifier passed to either
+ * of them.
+ *
+ * @remarks
+ * Never type-checks or executes the file -- see `link.ts` for how
+ * these raw facts get resolved into actual schema/docs data, including
+ * across files.
+ */
+export declare function parseSchemaFile(filePath: string, sourceText: string): FileParseResult;
+/**
+ * Collects named import bindings from one `import` statement into `imports`, keyed by local name.
+ *
+ * @remarks
+ * Exported for reuse by `scan-dependencies.ts`, which needs the same
+ * alias-aware named-import tracking this file already does for schema
+ * linking, just applied to arbitrary application source instead of schema
+ * files.
+ *
+ * @param imports - Mutated in place; a binding re-collected under the same local name overwrites the previous entry.
+ */
+export declare function collectImportBindings(statement: ts.ImportDeclaration, imports: Map<string, ImportBinding>): void;
+/** One schema entry's statically-discoverable shape -- presence facts, never evaluated/executed values. */
+export interface DiscoveredSchemaVariable {
+    /** The environment variable name (the schema's object key). */
+    readonly key: string;
+    /** Whether the entry declares a `default`. */
+    readonly hasDefault: boolean;
+    /** The default's statically-evaluated literal value, if `hasDefault` and it was a literal we could evaluate -- `{ ok: false }` when present but not statically resolvable, `undefined` when absent. */
+    readonly defaultValue: {
+        /** Always `true` in this branch. */
+        ok: true;
+        /** The evaluated literal value. */
+        value: unknown;
+    } | {
+        /** Always `false` in this branch: present but not statically resolvable. */
+        ok: false;
+    } | undefined;
+    /** Whether the entry declares a `processor`. */
+    readonly hasProcessor: boolean;
+    /** The processor function's source text, normalized to single-line, if `hasProcessor`. */
+    readonly processorSource: string | undefined;
+    /** Only present when the processor has an explicit `: T` return type annotation -- the one thing we treat as provable. */
+    readonly processorReturnType: string | undefined;
+    /** Whether the entry declares a `validator`. */
+    readonly hasValidator: boolean;
+    /** The validator function's source text, normalized to single-line, if `hasValidator`. */
+    readonly validatorSource: string | undefined;
+    /** The variable's statically-resolved `context`, if set to a non-empty string literal (see ADR 0022). `undefined` when absent, non-literal, or empty. */
+    readonly context: string | undefined;
+    /** Where this variable's own schema property (e.g. `SESSION_SECRET: z.string()`) is declared -- distinct from the *contract's* `declaration`/`documentation` (`link.ts`); every variable has exactly one of these, always. See ADR 0036. */
+    readonly declaration: SourcePosition;
+}
+/**
+ * Extracts one schema object literal's variables (processor/validator/default presence); never
+ * evaluates or executes the schema.
+ *
+ * @param contextLabel - Used only to build human-readable warning messages (e.g. the contract's export name).
+ * @param warnings - Mutated in place: one entry is pushed per skipped (non-static, invalid-key, or non-literal) property.
+ */
+export declare function extractSchemaVariables(schemaLiteral: ts.ObjectLiteralExpression, filePath: string, contextLabel: string, warnings: ParseWarning[], sourceFile: ts.SourceFile): DiscoveredSchemaVariable[];
+/** One variable's statically-extracted `documentEnv()` documentation, as declared in that call's `variables` entry for this key -- governance fields (`owner` .. `metadata`) are {@link EnvGovernanceFields}, resolved from static literals. */
+export interface DiscoveredVariableDocs extends EnvGovernanceFields {
+    /** The environment variable name this documentation applies to. */
+    readonly key: string;
+    /** Statically-resolved `description`, if set to a string literal. */
+    readonly description: string | undefined;
+    /** Statically-resolved `refreshInstructions`, if set to a string literal. */
+    readonly refreshInstructions: string | undefined;
+    /** Statically-resolved `setupInstructions`, if set to a string literal. */
+    readonly setupInstructions: string | undefined;
+    /** Statically-resolved `required`, if set to a boolean literal. */
+    readonly required: boolean | undefined;
+    /** Statically-resolved `deprecated`, if set to a boolean literal. */
+    readonly deprecated: boolean | undefined;
+    /** Statically-resolved `deprecatedReason`, if set to a string literal. */
+    readonly deprecatedReason: string | undefined;
+    /** Statically-resolved `removeBy`, if set to a string literal. */
+    readonly removeBy: string | undefined;
+    /** Statically-resolved `renamedFrom`, if set to a string literal. */
+    readonly renamedFrom: string | undefined;
+    /** Statically-extracted `evidence` sub-object -- the re-verified-every-run half of a variable's documentation, kept structurally apart from the declared-only fields above. `undefined` when the declaration has no `evidence` key at all. See {@link runtime.VariableEvidenceDocs} and ADR 0037. */
+    readonly evidence: DiscoveredVariableEvidence | undefined;
+}
+/** The statically-extracted contents of one variable's `evidence` sub-object. See {@link runtime.VariableEvidenceDocs}. */
+export interface DiscoveredVariableEvidence {
+    /** Well-formed `"path:line:column"` entries from `evidence.dynamicAccess`, if set to an array of string literals -- a malformed entry warns and is dropped, never included here. See ADR 0037. */
+    readonly dynamicAccess: readonly string[] | undefined;
+}
+/** A contract's statically-extracted `documentEnv()` documentation. */
+/** The `documentEnv()` contract-level documentation, resolved from static literals at the parse stage. Its governance fields (`owner` .. `metadata`) are {@link EnvGovernanceFields}. */
+export interface DiscoveredContractDocs extends EnvGovernanceFields {
+    /** Statically-resolved `name`, if set to a string literal. */
+    readonly name: string | undefined;
+    /** Statically-resolved `category`, if set to a string literal. */
+    readonly category: string | undefined;
+    /** Statically-resolved `exclusiveGroup`, if set to a string literal. */
+    readonly exclusiveGroup: string | undefined;
+    /** Defaults to `true` when the call's `active` field is absent or not statically resolvable. */
+    readonly active: boolean;
+    /** Statically-resolved `deprecated`, if set to a boolean literal. */
+    readonly deprecated: boolean | undefined;
+    /** Statically-resolved `deprecatedReason`, if set to a string literal. */
+    readonly deprecatedReason: string | undefined;
+    /** Per-variable documentation, keyed by variable name. */
+    readonly variables: ReadonlyMap<string, DiscoveredVariableDocs>;
+}
+/**
+ * Reads a `documentEnv()` call's second argument (the {@link runtime.ContractDocs} shape).
+ *
+ * @remarks
+ * Anything not a statically-resolvable literal warns and is skipped (falls back to
+ * "not set") rather than guessed at, same policy as schema-entry parsing.
+ *
+ * @param contextLabel - Used only to build human-readable warning messages.
+ * @param warnings - Mutated in place: one entry is pushed per unresolvable field.
+ */
+export declare function extractContractDocs(docsArg: ts.Expression | undefined, filePath: string, contextLabel: string, warnings: ParseWarning[]): DiscoveredContractDocs;
+/** Reads `createEnv`'s second argument (the {@link runtime.CreateEnvOptions} shape) for just `name`, if it's a statically-resolvable string literal. Used only for the docs fallback chain (`documentEnv`'s `name` wins if set); `source` is runtime-only and never read here. */
+export declare function extractCreateEnvOptionsName(optionsArg: ts.Expression | undefined): string | undefined;
+export {};
+//# sourceMappingURL=parse.d.ts.map

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

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

package/dist/.dts/build/reference-projections.d.ts

@@ -0,0 +1,156 @@
+/**
+ * env-cap's own built-in reference projections, declared through the exact
+ * same public `defineEvidenceProjection()` a consumer would use (ADR
+ * 0031/0032) -- no privileged internal path, no second way of reading the
+ * Evidence Model.
+ *
+ * This is deliberate dogfooding, not a convenience layer: `renderDocs()`'s
+ * Catalog/ownership/lifecycle sections and `renderUsageReport()`'s ownership
+ * table now source their underlying data through these projections, so the
+ * extensibility API is exercised by env-cap's own generated output on every
+ * single run. If a projector here can't express something, that's a real gap
+ * in the public API -- discovered by env-cap itself rather than by a consumer
+ * reporting it.
+ *
+ * Every projection is pure and derives *only* from `EvidenceModel`. None
+ * reads the filesystem, and none reaches back into `DiscoveredContract` --
+ * that would defeat the point, since a consumer only ever has the model.
+ */
+/** One variable, flattened across Contract/Ownership/Lifecycle Model into the row a Configuration Reference renders. */
+export interface ConfigurationReferenceEntry {
+    /** Root-relative, POSIX-separated path of the declaring contract. */
+    readonly file: string;
+    readonly exportName: string;
+    /** The declaring contract's display name, resolved from Contract Model -- the one model that owns it. */
+    readonly contractName: string;
+    readonly key: string;
+    readonly description: string | undefined;
+    /** Effective owner: the variable's own, falling back to its contract's. */
+    readonly owner: string | undefined;
+    /** Effective sensitivity: the variable's own, falling back to its contract's. Any string; see {@link runtime.VariableDocs.sensitivity}. */
+    readonly sensitivity: string | undefined;
+    readonly required: boolean | undefined;
+    readonly hasDefault: boolean;
+    readonly hasProcessor: boolean;
+    readonly hasValidator: boolean;
+    readonly expiresAt: string | undefined;
+    /** Whether the declaring contract is active. Inactive contracts are included -- the reference documents everything discovered, same scope the Catalog always had. */
+    readonly active: boolean;
+}
+/** The Configuration Reference projection's output shape. */
+export interface ConfigurationReference extends Record<string, unknown> {
+    /** The standing "declared, not verified" notice -- see `evidenceDisclaimer()`. Carried in the data, not only in a renderer, so a consumer projecting this to their own format can't accidentally drop it. */
+    readonly disclaimer: string;
+    /** Every declared variable across every discovered contract, sorted by contract file, then export name, then key. */
+    readonly entries: readonly ConfigurationReferenceEntry[];
+}
+/** The minimal shape {@link groupVariablesByOwner} needs -- structural, not pinned to one model, so the exact same grouping serves `OwnershipModel`'s already-resolved owners and `ContractModel`'s raw ones alike. */
+export interface OwnerBearingContract {
+    readonly owner: string | undefined;
+    readonly variables: readonly unknown[];
+}
+/** The element type of an {@link OwnerBearingContract}'s own `variables`, so callers never have to name it a second time. */
+type VariableOf<C> = C extends {
+    readonly variables: readonly (infer V)[];
+} ? V : never;
+/**
+ * Groups every variable under its effective owner (its own, falling back to
+ * its contract's), preserving input order within each owner.
+ *
+ * @remarks
+ * The single implementation of "who owns what, rolled up per owner", shared
+ * by the {@link ownershipSummary} projection and `docs.ts`'s own rendered
+ * ownership matrix. Kept as one function precisely so env-cap's generated
+ * Markdown and the projection a consumer reads can never disagree about the
+ * grouping -- the same reason `effectiveOwner()` is the single resolution
+ * rule (ADR 0028). Variables with no effective owner are omitted entirely
+ * rather than bucketed under a synthetic `"unowned"` key, which would read
+ * as a real team name; callers that need them ask for them separately.
+ *
+ * `ownerOf` is supplied by the caller so a model whose owners are already
+ * resolved (`OwnershipModel`) and one whose aren't (`ContractModel`) both
+ * work without this function guessing which it was handed.
+ */
+export declare function groupVariablesByOwner<C extends OwnerBearingContract>(contracts: readonly C[], ownerOf: (contract: C, variable: VariableOf<C>) => string | undefined): ReadonlyMap<string, readonly {
+    contract: C;
+    variable: VariableOf<C>;
+}[]>;
+/**
+ * Configuration Reference: every declared variable, with its effective owner
+ * and sensitivity already resolved, in one flat, sorted list.
+ *
+ * @remarks
+ * Resolution (variable's own value falling back to its contract's) happens
+ * here rather than being left to each consumer, so two readers of this
+ * projection can never disagree about who owns a variable -- the same reason
+ * `effectiveOwner()` exists on the generator side (ADR 0028).
+ */
+export declare const configurationReference: import("../evidence/define-projection.js").EvidenceProjection<ConfigurationReference>;
+/** One owner and everything attributed to them. */
+export interface OwnershipSummaryEntry {
+    /** The owner string exactly as declared. */
+    readonly owner: string;
+    /** Every variable this owner is the effective owner of, as `${contractName}.${key}`, sorted. */
+    readonly variables: readonly string[];
+    /** Every contract declaring this owner as its contract-level default, by display name, sorted. */
+    readonly contracts: readonly string[];
+}
+/** The Ownership summary projection's output shape. */
+export interface OwnershipSummary extends Record<string, unknown> {
+    /** See {@link ConfigurationReference.disclaimer}. */
+    readonly disclaimer: string;
+    /** One entry per distinct owner, sorted by owner. */
+    readonly owners: readonly OwnershipSummaryEntry[];
+    /** Every variable with no effective owner at all, as `${contractName}.${key}`, sorted. Named separately rather than bucketed under a synthetic `"unowned"` owner, so "nobody owns this" can never be mistaken for a real team name. */
+    readonly unowned: readonly string[];
+}
+/**
+ * Ownership summary: the inverse of Ownership Model's per-contract view --
+ * who owns what, rolled up per owner, plus an explicit unowned list.
+ */
+export declare const ownershipSummary: import("../evidence/define-projection.js").EvidenceProjection<OwnershipSummary>;
+/** One contract- or variable-level `expiresAt` inside the configured window. */
+export interface ExpiringSoonEntry {
+    /** Root-relative, POSIX-separated path of the declaring contract. */
+    readonly file: string;
+    readonly exportName: string;
+    /** The declaring contract's display name, resolved from Contract Model. */
+    readonly contractName: string;
+    /** `undefined` for a contract-level expiry, set for a per-variable one. */
+    readonly key: string | undefined;
+    /** The raw ISO date string, exactly as declared -- never reformatted. */
+    readonly expiresAt: string;
+    /** Days remaining as of the run that produced this evidence; negative when already expired. */
+    readonly daysRemaining: number;
+    /** `true` when `daysRemaining` is negative -- the deadline has already passed. */
+    readonly expired: boolean;
+    /** How to obtain a replacement value, if the declaration says. */
+    readonly refreshInstructions: string | undefined;
+    /** Effective owner, so a reader knows who to chase without a second lookup. */
+    readonly owner: string | undefined;
+}
+/** The Expiring-Soon projection's output shape. */
+export interface ExpiringSoonReport extends Record<string, unknown> {
+    /** See {@link ConfigurationReference.disclaimer}. */
+    readonly disclaimer: string;
+    /** Every entry inside the window, soonest-first (already-expired entries lead, most-overdue first). */
+    readonly entries: readonly ExpiringSoonEntry[];
+    /** How many of `entries` are already past their `expiresAt`. */
+    readonly expiredCount: number;
+}
+/**
+ * Expiring-Soon report: Lifecycle Model's `expiring` view, joined with
+ * ownership and refresh instructions so a reader can act on a row without
+ * cross-referencing three other models by hand.
+ *
+ * @remarks
+ * The window itself was applied upstream, when Lifecycle Model was built --
+ * this projection deliberately does not re-filter by a date of its own.
+ * Recomputing "soon" here would make the projection's answer depend on when
+ * it happened to be *read* rather than when the evidence was *generated*,
+ * which is exactly the reproducibility property the Evidence Model exists to
+ * preserve.
+ */
+export declare const expiringSoonReport: import("../evidence/define-projection.js").EvidenceProjection<ExpiringSoonReport>;
+export {};
+//# sourceMappingURL=reference-projections.d.ts.map

package/dist/.dts/build/reference-projections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-projections.d.ts","sourceRoot":"","sources":["../../../src/build/reference-projections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAOH,wHAAwH;AACxH,MAAM,WAAW,2BAA2B;IAC1C,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,yGAAyG;IACzG,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,2IAA2I;IAC3I,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,qKAAqK;IACrK,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CACzB;AAED,6DAA6D;AAC7D,MAAM,WAAW,sBAAuB,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACrE,6MAA6M;IAC7M,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,qHAAqH;IACrH,QAAQ,CAAC,OAAO,EAAE,SAAS,2BAA2B,EAAE,CAAA;CACzD;AAoBD,uNAAuN;AACvN,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,QAAQ,CAAC,SAAS,EAAE,SAAS,OAAO,EAAE,CAAA;CACvC;AAED,6HAA6H;AAC7H,KAAK,UAAU,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,CAAA;CAAE,GAAG,CAAC,GAAG,KAAK,CAAA;AAEvF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,oBAAoB,EAClE,SAAS,EAAE,SAAS,CAAC,EAAE,EACvB,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,MAAM,GAAG,SAAS,GACpE,WAAW,CAAC,MAAM,EAAE,SAAS;IAAE,QAAQ,EAAE,CAAC,CAAC;IAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,CAAA;CAAE,EAAE,CAAC,CAY1E;AAED;;;;;;;;;GASG;AAYH,eAAO,MAAM,sBAAsB,uFA0BjC,CAAA;AAEF,mDAAmD;AACnD,MAAM,WAAW,qBAAqB;IACpC,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,gGAAgG;IAChG,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC,kGAAkG;IAClG,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;CACtC;AAED,uDAAuD;AACvD,MAAM,WAAW,gBAAiB,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC/D,qDAAqD;IACrD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,SAAS,qBAAqB,EAAE,CAAA;IACjD,uOAAuO;IACvO,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC;AAED;;;GAGG;AAEH,eAAO,MAAM,gBAAgB,iFA6C3B,CAAA;AAEF,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,+FAA+F;IAC/F,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,kEAAkE;IAClE,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAA;IAChD,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;CACnC;AAED,mDAAmD;AACnD,MAAM,WAAW,kBAAmB,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACjE,qDAAqD;IACrD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,uGAAuG;IACvG,QAAQ,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAA;IAC9C,gEAAgE;IAChE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAC9B;AAED;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,kBAAkB,mFAkD7B,CAAA"}

package/dist/.dts/build/resolution/resolve-import.d.ts

@@ -0,0 +1,53 @@
+import type { BuildFileSystem } from "../types.js";
+import { type PackageSchemaResolutionResult } from "./resolve-package-schema.js";
+import { type AliasResolutionCache, type TsconfigPathsResolution } from "./resolve-tsconfig-paths.js";
+/**
+ * Resolves a relative import specifier (as written in source: `"./schema.js"`,
+ * matching this codebase's own convention of `.js`-suffixed relative imports
+ * pointing at `.ts` source files) to an absolute file path, relative to the
+ * file that contains the import.
+ *
+ * @remarks
+ * Deliberately narrow: only handles a direct relative specifier resolving to
+ * a real `.ts`/`.tsx` file on disk. Bare/package specifiers, namespace
+ * imports, and anything requiring real module resolution (re-export chains,
+ * `exports` map lookups, etc.) return `undefined` -- the caller treats that
+ * as "couldn't statically link" and warns rather than guesses, the same
+ * philosophy `evaluateLiteral` already uses for non-literal expressions.
+ *
+ * @returns The resolved absolute path, or `undefined` when the specifier isn't relative or doesn't resolve to a real file.
+ */
+export declare function resolveRelativeImport(importingFile: string, specifier: string, fs: BuildFileSystem): Promise<string | undefined>;
+/** Shared inputs threaded through every call to {@link resolveImportSpecifier} for one discovery/link run. */
+export interface ImportResolutionContext {
+    /** The filesystem capability -- `./build` never imports `node:fs` (ADR 0040). */
+    readonly fs: BuildFileSystem;
+    /** Absolute path of the project root, used to resolve package specifiers. */
+    readonly root: string;
+    /** Explicit allowlist -- see ADR 0014. Empty/omitted means package resolution never fires, identical to today's behavior. */
+    readonly packages: readonly string[];
+    /** Memoizes package resolution per specifier across the whole run -- see `resolvePackageImport`'s own doc comment for why. */
+    readonly cache: Map<string, Promise<PackageSchemaResolutionResult>>;
+    /** Parsed `tsconfig.json` `paths`/`baseUrl`, or `undefined` when alias resolution found nothing to do or was disabled -- see ADR 0023. */
+    readonly tsconfigPaths: TsconfigPathsResolution | undefined;
+    /** Memoizes alias resolution across the whole run -- see `resolveAliasImport`'s own doc comment for why. Always allocated, even when `tsconfigPaths` is `undefined`, mirroring `cache` above. */
+    readonly aliasCache: AliasResolutionCache;
+}
+/**
+ * The one specifier-resolution entry point `link.ts` and `dependency-graph.ts`
+ * call, instead of each duplicating a
+ * `(await resolveRelativeImport(...)) ?? resolveAliasImport(...) ?? (await resolvePackageImport(...))`
+ * chain at every call site.
+ *
+ * @remarks
+ * Purely a composition point -- no new resolution logic lives here. Tries, in order: the
+ * relative resolver (cheap, no `fs.stat` beyond the local filesystem check it already
+ * does); tsconfig path-alias resolution (ADR 0023, on by default) for a bare specifier
+ * matching the project's own `tsconfig.json` `paths`/`baseUrl`; then package resolution
+ * (ADR 0014) for a bare specifier matching an allow-listed package name. Alias resolution
+ * runs before package resolution because it resolves the consuming project's own local
+ * source (already-trusted, no versioning boundary), the same precedence relative
+ * resolution already has over package resolution.
+ */
+export declare function resolveImportSpecifier(importingFile: string, specifier: string, context: ImportResolutionContext): Promise<string | undefined>;
+//# sourceMappingURL=resolve-import.d.ts.map

package/dist/.dts/build/resolution/resolve-import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-import.d.ts","sourceRoot":"","sources":["../../../../src/build/resolution/resolve-import.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,EAEL,KAAK,6BAA6B,EACnC,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC7B,MAAM,6BAA6B,CAAA;AAEpC;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,qBAAqB,CACzC,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAe7B;AA0BD,8GAA8G;AAC9G,MAAM,WAAW,uBAAuB;IACtC,iFAAiF;IACjF,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAA;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,6HAA6H;IAC7H,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,8HAA8H;IAC9H,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,6BAA6B,CAAC,CAAC,CAAA;IACnE,0IAA0I;IAC1I,QAAQ,CAAC,aAAa,EAAE,uBAAuB,GAAG,SAAS,CAAA;IAC3D,iMAAiM;IACjM,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAA;CAC1C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,sBAAsB,CAC1C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAe7B"}

package/dist/.dts/build/resolution/resolve-package-schema.d.ts

@@ -0,0 +1,83 @@
+import type { ParseWarning } from "../parse.js";
+import type { BuildFileSystem } from "../types.js";
+/** 1 MiB. New hardening specific to this trust tier -- a package crosses a
+ *  real versioning/trust boundary that locally-discovered source doesn't,
+ *  so this caps the cost of parsing an oversized or adversarial file before
+ *  any of its content is even read into memory. See ADR 0014. */
+export declare const MAX_PACKAGE_SCHEMA_FILE_BYTES = 1048576;
+type PackageResolutionFailureCode = "PACKAGE_NOT_FOUND" | "MALFORMED_PACKAGE_JSON" | "FIELD_MISSING" | "INVALID_EXTENSION" | "OUTSIDE_PACKAGE" | "FILE_TOO_LARGE";
+/** Both the authored and resolved forms are kept -- diagnostics benefit from
+ *  showing exactly what a package author wrote versus what it resolved to. */
+export interface PackageOrigin {
+    /** The allow-listed package name that declared this schema. */
+    readonly packageName: string;
+    /** The `"envCap.schema"` value exactly as the package author wrote it. */
+    readonly declaredField: string;
+    /** Absolute, realpath-canonicalized path to the resolved schema file. */
+    readonly resolvedFile: string;
+    /** Absolute, realpath-canonicalized path to the package's own directory. */
+    readonly packageDir: string;
+}
+export type PackageSchemaResolutionResult = {
+    readonly ok: true;
+    readonly origin: PackageOrigin;
+} | {
+    readonly ok: false;
+    readonly code: PackageResolutionFailureCode;
+    readonly reason: string;
+};
+/**
+ * Resolves one allow-listed package name. Memoized in a caller-owned
+ * `cache` (one per `generate*()` invocation, shared with linking/dependency-
+ * graph resolution) so a name referenced from multiple places -- multiple
+ * scanned files bare-importing the same package, or a duplicate entry in
+ * `packages` -- is only ever resolved once. The cache is populated with the
+ * in-flight promise before it settles, so concurrent callers await the same
+ * resolution rather than racing duplicate work.
+ */
+export declare function resolvePackageSchemaFile(packageName: string, root: string, cache: Map<string, Promise<PackageSchemaResolutionResult>>, fs: BuildFileSystem): Promise<PackageSchemaResolutionResult>;
+interface ResolvedPackageFile {
+    readonly packageName: string;
+    readonly file: string;
+}
+export interface ResolvePackagesResult {
+    readonly files: readonly ResolvedPackageFile[];
+    /** Keyed by resolved file path, for `DiscoveredContract.packageOrigin` lookups downstream. */
+    readonly origins: ReadonlyMap<string, PackageOrigin>;
+    readonly warnings: readonly ParseWarning[];
+}
+/**
+ * Resolves every allow-listed package name. Input is deduplicated first, so
+ * a duplicate entry in `packages` (accidental or defensive) produces exactly
+ * one resolution attempt and, on failure, exactly one warning -- never two.
+ * Never throws: every failure becomes one `ParseWarning`, consistent with
+ * every other static-analysis boundary in this codebase.
+ */
+export declare function resolveAllowlistedPackages(packages: readonly string[], root: string, cache: Map<string, Promise<PackageSchemaResolutionResult>>, fs: BuildFileSystem): Promise<ResolvePackagesResult>;
+/**
+ * Combines local schema-discovery hits with package-resolved files into one
+ * deduplicated list, keyed by realpath rather than lexical absolute path --
+ * package-resolved files are already realpath-canonicalized (see
+ * `resolveUncached` above), but local `discoverSchemaFiles()` hits are plain
+ * `readdir`-derived absolute paths that may themselves traverse a symlink (a
+ * symlinked `root`, or an included path reached through one). Deduplicating
+ * on the lexical path alone would miss the case where the same physical file
+ * is reached twice through two different symlinked routes -- one via local
+ * glob discovery, one via package resolution -- and silently double-count it
+ * into two identical contracts, including the more mundane case of a package
+ * that's both locally glob-reachable (e.g. during a monorepo migration) and
+ * explicitly allow-listed. On a collision, the local path string identity
+ * wins (the package-resolved duplicate is dropped).
+ */
+export declare function mergeLocalAndPackageFiles(localFiles: readonly string[], packageFiles: readonly string[], fs: BuildFileSystem): Promise<string[]>;
+/**
+ * Bare-specifier-to-allowlist matching, used by `resolve-import.ts`'s
+ * `resolveImportSpecifier()` as its package-resolution fallback. Only ever
+ * attempts resolution for a specifier that is (or is a subpath of) an
+ * allow-listed package name -- any other bare specifier is not this
+ * mechanism's concern and returns `undefined` immediately, identical to
+ * `resolveRelativeImport()`'s existing bare-specifier no-op.
+ */
+export declare function resolvePackageImport(specifier: string, allowedPackages: readonly string[], root: string, cache: Map<string, Promise<PackageSchemaResolutionResult>>, fs: BuildFileSystem): Promise<string | undefined>;
+export {};
+//# sourceMappingURL=resolve-package-schema.d.ts.map

package/dist/.dts/build/resolution/resolve-package-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-package-schema.d.ts","sourceRoot":"","sources":["../../../../src/build/resolution/resolve-package-schema.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAuBlD;;;iEAGiE;AACjE,eAAO,MAAM,6BAA6B,UAAY,CAAA;AAItD,KAAK,4BAA4B,GAC7B,mBAAmB,GACnB,wBAAwB,GACxB,eAAe,GACf,mBAAmB,GACnB,iBAAiB,GACjB,gBAAgB,CAAA;AAEpB;8EAC8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED,MAAM,MAAM,6BAA6B,GACrC;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,4BAA4B,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAgNhG;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,6BAA6B,CAAC,CAAC,EAC1D,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,6BAA6B,CAAC,CAOxC;AAED,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,CAAA;IAC9C,8FAA8F;IAC9F,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IACpD,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAA;CAC3C;AAED;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,6BAA6B,CAAC,CAAC,EAC1D,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,qBAAqB,CAAC,CAuBhC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,MAAM,EAAE,CAAC,CAuBnB;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,SAAS,MAAM,EAAE,EAClC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,6BAA6B,CAAC,CAAC,EAC1D,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAqB7B"}