@maverickcer/env-cap 0.2.0

package/dist/.dts/helpers/processors.d.ts

@@ -0,0 +1,32 @@
+import type { Processor } from "../runtime/index.js";
+/** Splits a delimited string (or passes through an array) into items, running each through `processors` in order. */
+export declare function toArray<T>(separator?: string | RegExp, processors?: Processor<unknown>[]): Processor<T[]>;
+/** Decodes a base64 string into a `Buffer`. */
+export declare function base64(): Processor<Buffer>;
+/** Coerces a value to a `bigint`. */
+export declare function toBigInt(): Processor<bigint>;
+/** Coerces common boolean-like strings (`true`/`1`/`yes`/`on`, and their opposites) into a real boolean. */
+export declare function toBoolean(): Processor<boolean>;
+/** Parses a value into a `Date`. */
+export declare function toDate(): Processor<Date>;
+/** Coerces a value to a number and requires it to be an integer. */
+export declare function toInteger(): Processor<number>;
+/** Parses a JSON string; passes non-string values through unchanged. */
+export declare function parseJSON<T = unknown>(): Processor<T>;
+/** Lowercases a string (coercing nullish values to `""` first). */
+export declare function toLowerCase(): Processor<string>;
+/** Coerces a value to a number, rejecting empty/whitespace-only strings instead of silently resolving to `0`. */
+export declare function toNumber(): Processor<number>;
+/** Compiles a value into a `RegExp`. */
+export declare function toRegExp(): Processor<RegExp>;
+/** Splits a string on `separator` into a trimmed string array; returns `[]` for non-string input. */
+export declare function split(separator?: string): Processor<string[]>;
+/** Coerces a value to a string, treating nullish values as `""`. */
+export declare function toString(): Processor<string>;
+/** Trims surrounding whitespace from a string (coercing nullish values to `""` first). */
+export declare function trim(): Processor<string>;
+/** Uppercases a string (coercing nullish values to `""` first). */
+export declare function toUpperCase(): Processor<string>;
+/** Parses a value into a `URL`, treating nullish values as `""` first. */
+export declare function toURL(): Processor<URL>;
+//# sourceMappingURL=processors.d.ts.map

package/dist/.dts/helpers/processors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processors.d.ts","sourceRoot":"","sources":["../../../src/helpers/processors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAepD,qHAAqH;AACrH,wBAAgB,OAAO,CAAC,CAAC,EACvB,SAAS,GAAE,MAAM,GAAG,MAAY,EAChC,UAAU,GAAE,SAAS,CAAC,OAAO,CAAC,EAAO,GACpC,SAAS,CAAC,CAAC,EAAE,CAAC,CAYhB;AAED,+CAA+C;AAC/C,wBAAgB,MAAM,IAAI,SAAS,CAAC,MAAM,CAAC,CAQ1C;AAED,qCAAqC;AACrC,wBAAgB,QAAQ,IAAI,SAAS,CAAC,MAAM,CAAC,CAQ5C;AAED,4GAA4G;AAC5G,wBAAgB,SAAS,IAAI,SAAS,CAAC,OAAO,CAAC,CAiB9C;AAED,oCAAoC;AACpC,wBAAgB,MAAM,IAAI,SAAS,CAAC,IAAI,CAAC,CAUxC;AAED,oEAAoE;AACpE,wBAAgB,SAAS,IAAI,SAAS,CAAC,MAAM,CAAC,CAU7C;AAED,wEAAwE;AACxE,wBAAgB,SAAS,CAAC,CAAC,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,CAcrD;AAED,mEAAmE;AACnE,wBAAgB,WAAW,IAAI,SAAS,CAAC,MAAM,CAAC,CAE/C;AAED,iHAAiH;AACjH,wBAAgB,QAAQ,IAAI,SAAS,CAAC,MAAM,CAAC,CAqB5C;AAED,wCAAwC;AACxC,wBAAgB,QAAQ,IAAI,SAAS,CAAC,MAAM,CAAC,CAQ5C;AAED,qGAAqG;AACrG,wBAAgB,KAAK,CAAC,SAAS,SAAM,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,CAM1D;AAED,oEAAoE;AACpE,wBAAgB,QAAQ,IAAI,SAAS,CAAC,MAAM,CAAC,CAU5C;AAED,0FAA0F;AAC1F,wBAAgB,IAAI,IAAI,SAAS,CAAC,MAAM,CAAC,CAExC;AAED,mEAAmE;AACnE,wBAAgB,WAAW,IAAI,SAAS,CAAC,MAAM,CAAC,CAE/C;AAED,0EAA0E;AAC1E,wBAAgB,KAAK,IAAI,SAAS,CAAC,GAAG,CAAC,CAetC"}

package/dist/.dts/helpers/validators.d.ts

@@ -0,0 +1,68 @@
+import type { Validator } from "../runtime/index.js";
+/** Passes when the date value is strictly after `date`. */
+export declare function after(date: Date): Validator<Date>;
+/** Passes only when every wrapped validator passes; returns the first failing message. */
+export declare function all<T>(...validators: Validator<T>[]): Validator<T>;
+/** Passes when at least one wrapped validator passes. */
+export declare function any<T>(...validators: Validator<T>[]): Validator<T>;
+/** Passes when the date value is strictly before `date`. */
+export declare function before(date: Date): Validator<Date>;
+/** Identity wrapper for a hand-written `Validator<T>` -- no behavior change, just a fluent entry point alongside the other helpers. */
+export declare function custom<T>(validator: Validator<T>): Validator<T>;
+/** Passes for a plausibly-shaped email address (`local@domain`). */
+export declare function email(): Validator<string>;
+/** Passes when the string ends with `suffix`. */
+export declare function endsWith(suffix: string): Validator<string>;
+/** Passes when the number is finite (rejects `Infinity`/`-Infinity`/`NaN`). */
+export declare function finite(): Validator<number>;
+/** Passes when the date is strictly after the current time. */
+export declare function future(): Validator<Date>;
+/** Passes when the string contains `text` as a substring. */
+export declare function includes(text: string): Validator<string>;
+/** Passes when the number is an integer. */
+export declare function integer(): Validator<number>;
+/** Passes when the string's length is exactly `expected`. */
+export declare function length(expected: number): Validator<string>;
+/** Passes when the string matches `pattern`; `message` overrides the default failure text. */
+export declare function matches(pattern: RegExp, message?: string): Validator<string>;
+/** Passes when the number is less than or equal to `maximum`. */
+export declare function max(maximum: number): Validator<number>;
+/** Passes when the array has at most `maximum` items. */
+export declare function maxItems<T>(maximum: number): Validator<T[]>;
+/** Passes when the string's length is at most `length`. */
+export declare function maxLength(length: number): Validator<string>;
+/** Passes when the number is greater than or equal to `minimum`. */
+export declare function min(minimum: number): Validator<number>;
+/** Passes when the array has at least `minimum` items. */
+export declare function minItems<T>(minimum: number): Validator<T[]>;
+/** Passes when the string's length is at least `length`. */
+export declare function minLength(length: number): Validator<string>;
+/** Passes when the number is strictly negative. */
+export declare function negative(): Validator<number>;
+/** Inverts a validator: passes when the wrapped validator fails, and vice versa. */
+export declare function not<T>(validator: Validator<T>): Validator<T>;
+/** Passes when the value is one of the `allowed` values. */
+export declare function oneOf<T>(allowed: readonly T[]): Validator<T>;
+/** Passes when the value is undefined, otherwise delegates to the provided validator. */
+export declare function optional<T>(validator: Validator<T>): Validator<T | undefined>;
+/** Passes when the date is strictly before the current time. */
+export declare function past(): Validator<Date>;
+/** Passes when the number is strictly positive. */
+export declare function positive(): Validator<number>;
+/** Passes when the number is within `[minimum, maximum]` inclusive. */
+export declare function range(minimum: number, maximum: number): Validator<number>;
+/** Runs the wrapped validator but replaces its failure message with `message`. */
+export declare function refine<T>(validator: Validator<T>, message: string): Validator<T>;
+/** Passes when the value is defined and, unless `allowEmptyString` is set, non-empty. */
+export declare function required(allowEmptyString?: boolean): Validator<unknown>;
+/** Passes when the number is a safe integer (`Number.isSafeInteger`). */
+export declare function safeInteger(): Validator<number>;
+/** Passes when every item in the array is unique. */
+export declare function unique<T>(): Validator<T[]>;
+/** Passes when the string is a valid absolute URL. */
+export declare function url(): Validator<string>;
+/** Passes when the string is a valid UUID of one of the given `versions` (default: any of 1-8). */
+export declare function uuid(versions?: readonly number[]): Validator<string>;
+/** Shorthand for `uuid([version])` -- passes only for that exact UUID version. */
+export declare function uuidVersion(number: number): Validator<string>;
+//# sourceMappingURL=validators.d.ts.map

package/dist/.dts/helpers/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../../src/helpers/validators.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAEpD,2DAA2D;AAC3D,wBAAgB,KAAK,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,CAEjD;AAED,0FAA0F;AAC1F,wBAAgB,GAAG,CAAC,CAAC,EAAE,GAAG,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CASlE;AAED,yDAAyD;AACzD,wBAAgB,GAAG,CAAC,CAAC,EAAE,GAAG,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAQlE;AAED,4DAA4D;AAC5D,wBAAgB,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,CAElD;AAED,uIAAuI;AACvI,wBAAgB,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAE/D;AAED,oEAAoE;AACpE,wBAAgB,KAAK,IAAI,SAAS,CAAC,MAAM,CAAC,CAEzC;AAED,iDAAiD;AACjD,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAE1D;AAED,+EAA+E;AAC/E,wBAAgB,MAAM,IAAI,SAAS,CAAC,MAAM,CAAC,CAE1C;AAED,+DAA+D;AAC/D,wBAAgB,MAAM,IAAI,SAAS,CAAC,IAAI,CAAC,CAExC;AAED,6DAA6D;AAC7D,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAExD;AAED,4CAA4C;AAC5C,wBAAgB,OAAO,IAAI,SAAS,CAAC,MAAM,CAAC,CAE3C;AAED,6DAA6D;AAC7D,wBAAgB,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAE1D;AAED,8FAA8F;AAC9F,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAG5E;AAED,iEAAiE;AACjE,wBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAGtD;AAED,yDAAyD;AACzD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,EAAE,CAAC,CAE3D;AAED,2DAA2D;AAC3D,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAE3D;AAED,oEAAoE;AACpE,wBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAGtD;AAED,0DAA0D;AAC1D,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,EAAE,CAAC,CAE3D;AAED,4DAA4D;AAC5D,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAE3D;AAED,mDAAmD;AACnD,wBAAgB,QAAQ,IAAI,SAAS,CAAC,MAAM,CAAC,CAE5C;AAED,oFAAoF;AACpF,wBAAgB,GAAG,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAG5D;AAED,4DAA4D;AAC5D,wBAAgB,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAE5D;AAED,yFAAyF;AACzF,wBAAgB,QAAQ,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,CAAC,CAK7E;AAED,gEAAgE;AAChE,wBAAgB,IAAI,IAAI,SAAS,CAAC,IAAI,CAAC,CAEtC;AAED,mDAAmD;AACnD,wBAAgB,QAAQ,IAAI,SAAS,CAAC,MAAM,CAAC,CAE5C;AAED,uEAAuE;AACvE,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAIzE;AAED,kFAAkF;AAClF,wBAAgB,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,CAEhF;AAED,yFAAyF;AACzF,wBAAgB,QAAQ,CAAC,gBAAgB,UAAQ,GAAG,SAAS,CAAC,OAAO,CAAC,CAYrE;AAED,yEAAyE;AACzE,wBAAgB,WAAW,IAAI,SAAS,CAAC,MAAM,CAAC,CAE/C;AAED,qDAAqD;AACrD,wBAAgB,MAAM,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,EAAE,CAAC,CAG1C;AAED,sDAAsD;AACtD,wBAAgB,GAAG,IAAI,SAAS,CAAC,MAAM,CAAC,CASvC;AAED,mGAAmG;AACnG,wBAAgB,IAAI,CAAC,QAAQ,GAAE,SAAS,MAAM,EAA6B,GAAG,SAAS,CAAC,MAAM,CAAC,CAmB9F;AAED,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAE7D"}

package/dist/.dts/node/index.d.ts

@@ -0,0 +1,2 @@
+export { nodeBuildFileSystem } from "../cli/filesystem.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/.dts/node/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/node/index.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/.dts/runtime/cache.d.ts

@@ -0,0 +1,20 @@
+import type { EnvValidationError } from "./errors.js";
+import type { validateEnvResult } from "./types.js";
+type CacheStatus = "uninitialized" | "validating" | "ready" | "failed";
+export interface CacheState {
+    status: CacheStatus;
+    /** ids of every contract validated as part of this initialization, so resetEnvCache() can clean up precisely. */
+    contractIds: Set<symbol>;
+    result?: validateEnvResult;
+    error?: EnvValidationError;
+    inFlight?: Promise<validateEnvResult>;
+}
+export declare function getState(): CacheState;
+export declare function getContractValues(id: symbol): Readonly<Record<string, unknown>> | undefined;
+export declare function setContractValues(id: symbol, values: Readonly<Record<string, unknown>>): void;
+export declare function getContractError(id: symbol): EnvValidationError | undefined;
+export declare function setContractError(id: symbol, error: EnvValidationError): void;
+/** Clears cached state: the global status plus every contract validated as part of it. */
+export declare function resetCache(): void;
+export {};
+//# sourceMappingURL=cache.d.ts.map

package/dist/.dts/runtime/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/runtime/cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEnD,KAAK,WAAW,GAAG,eAAe,GAAG,YAAY,GAAG,OAAO,GAAG,QAAQ,CAAA;AAEtE,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,WAAW,CAAA;IACnB,iHAAiH;IACjH,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACxB,MAAM,CAAC,EAAE,iBAAiB,CAAA;IAC1B,KAAK,CAAC,EAAE,kBAAkB,CAAA;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAA;CACtC;AAqBD,wBAAgB,QAAQ,IAAI,UAAU,CAErC;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAE3F;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAE7F;AAED,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAE3E;AAED,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAE5E;AAED,0FAA0F;AAC1F,wBAAgB,UAAU,IAAI,IAAI,CAMjC"}

package/dist/.dts/runtime/create.d.ts

@@ -0,0 +1,20 @@
+import type { CreateEnvOptions, EnvContract, EnvSchema } from "./types.js";
+/**
+ * Declares a feature's environment contract. Colocate this call with the
+ * feature that consumes the variables (e.g. `features/payments/env.schema.ts`).
+ *
+ * @remarks
+ * `createEnv` is runtime-only: `processor`/`validator`/`default` are the
+ * whole vocabulary, because they're the only fields {@link validateEnv} actually
+ * reads. Documentation -- description, ownership, lifecycle, category, and
+ * everything else that only exists to generate docs -- lives in a separate
+ * {@link documentEnv} call (see `document.ts`), which is entirely optional and
+ * never required for this to work.
+ *
+ * @returns An {@link EnvContract} exposing one read-only getter per key -- there is no
+ * global env object, only per-feature contracts like `paymentsEnv.STRIPE_KEY`. Accessing a
+ * key throws until {@link validateEnv} has run successfully for the runtime this contract
+ * was passed to.
+ */
+export declare function createEnv<S extends EnvSchema>(schema: S, options?: CreateEnvOptions): EnvContract<S>;
+//# sourceMappingURL=create.d.ts.map

package/dist/.dts/runtime/create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../../src/runtime/create.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAqB,gBAAgB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAI7F;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,SAAS,EAC3C,MAAM,EAAE,CAAC,EACT,OAAO,GAAE,gBAAqB,GAC7B,WAAW,CAAC,CAAC,CAAC,CAmDhB"}

package/dist/.dts/runtime/document.d.ts

@@ -0,0 +1,181 @@
+import type { EnvSchema } from "./types.js";
+/**
+ * Developer-supplied evidence assertions for one variable -- categorically
+ * different from every field on {@link VariableDocs}: those are
+ * declared-and-never-verified, while `dynamicAccess` is re-checked against
+ * reality on every run (fresh / stale / missing). Kept structurally separate,
+ * in `VariableDocs.evidence` rather than folded in alongside `description`/
+ * `owner`/..., specifically so that different epistemic status is visible in
+ * the shape itself and not only in a doc comment. See ADR 0037.
+ */
+interface VariableEvidenceDocs {
+    /**
+     * Citation(s) of where this variable is actually read dynamically --
+     * somewhere env-cap's own static AST scan can't see (a shell script, a
+     * Docker entrypoint, a sibling service). Each entry is a
+     * `"<relative-path>:<line>:<column>"` citation.
+     *
+     * @remarks
+     * A developer's re-acknowledgment that access happens, never a claim
+     * env-cap itself observed anything -- tracked as its own independent fact
+     * and never folded into the AST-derived `VariableAccessStatus`. Re-verified
+     * every run: a citation whose file no longer exists, or whose content has
+     * visibly changed since it was last acknowledged, is flagged rather than
+     * trusted forever.
+     */
+    dynamicAccess?: readonly string[];
+}
+/**
+ * Per-variable documentation. Every field is optional and unconstrained on
+ * purpose -- there is no required shape, so documenting a variable never
+ * fights the type checker, and you can add a field the generator doesn't
+ * know about yet without it being rejected.
+ */
+export interface VariableDocs {
+    /** Human-readable explanation of what this variable is and what it controls. */
+    description?: string;
+    /** Who owns this variable (a team, a handle, whatever your org uses). Overrides the contract's own `owner` for this key. */
+    owner?: string;
+    /**
+     * How sensitive this variable's value is. Overrides the contract's own `sensitivity` for this
+     * key.
+     *
+     * @remarks
+     * Deliberately an open `string`, not a closed union: an org's own sensitivity vocabulary is its
+     * own, and a level env-cap doesn't recognize is always honored, never dropped. The generator
+     * still reports a `NONSTANDARD_SENSITIVITY_LEVEL` finding (severity `info`, never blocking) for
+     * anything outside `secret`/`credential`/`pii`/`config`, so vocabulary drift stays visible
+     * without being enforced.
+     */
+    sensitivity?: string;
+    /** ISO date string (e.g. "2026-06-01") -- when this variable's current value stops being valid (a key rotation deadline, a sunset date, etc.). */
+    expiresAt?: string;
+    /** How to get a new value before/when it expires (e.g. "Rotate in the Stripe dashboard, then redeploy."). */
+    refreshInstructions?: string;
+    /**
+     * Explicit, actionable instructions for obtaining this variable's value the *first* time --
+     * where `refreshInstructions` is "how to rotate it once you already have one," this is "how to
+     * get one at all" (e.g. "Create a restricted API key in the Stripe dashboard under Developers ->
+     * API keys, scoped to read/write Charges."). A named field specifically so this can render as
+     * its own labeled line in generated docs, rather than requiring a `metadata.setup`-style
+     * convention with no dedicated rendering or type checking.
+     */
+    setupInstructions?: string;
+    /** Documentation-level assertion that this variable must be set. Independent of how (or whether) a validator actually enforces it. */
+    required?: boolean;
+    /** Marks this variable as being phased out. Independent of `expiresAt` (a rotation/sunset date) and of the contract-level `active` switch (on/off, not a phase-out signal). */
+    deprecated?: boolean;
+    /** Why this variable is deprecated, and/or what to use instead. Only meaningful alongside `deprecated: true`. */
+    deprecatedReason?: string;
+    /** ISO date string -- by when a deprecated variable must be removed. Only meaningful alongside `deprecated: true`. */
+    removeBy?: string;
+    /** The previous environment variable name this one replaces, if this declaration is the result of a rename. Lets the Change Model correlate a remove+add pair into a single rename entry instead of two unrelated changes. */
+    renamedFrom?: string;
+    /** Why this variable's value is collected/used -- a framework-agnostic fact (pairs with `legalBasis`; a specific citation like a GDPR article belongs in `metadata` instead). Overrides the contract's own `purpose` for this key. */
+    purpose?: string;
+    /** The legal basis this variable's collection/use relies on -- framework-agnostic (e.g. "user consent," "contractual necessity"), never a specific statute name. Overrides the contract's own `legalBasis` for this key. */
+    legalBasis?: string;
+    /** Descriptive retention policy (e.g. "delete after 90 days"). A policy statement, not a computed value -- unlike `expiresAt`, nothing parses or evaluates this. Overrides the contract's own `retention` for this key. */
+    retention?: string;
+    /** Where this variable's value is/must be stored (a region, or a permitted set of regions). Overrides the contract's own `dataResidency` for this key. */
+    dataResidency?: string | string[];
+    /** Documentation-level assertion that this variable's handling must be auditable. Overrides the contract's own `auditRequired` for this key. */
+    auditRequired?: boolean;
+    /**
+     * Developer-supplied evidence assertions for this variable -- verified over
+     * time, unlike every other field above, which is declared and never
+     * verified. Kept structurally separate for exactly that reason; see
+     * {@link VariableEvidenceDocs}.
+     */
+    evidence?: VariableEvidenceDocs;
+    /**
+     * Structured, unsupported-key documentation -- any primitive or object value, for anything that
+     * doesn't warrant its own named field. A previously-supported top-level key belongs in a named
+     * field above instead of here once one exists for it.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Contract-level documentation, plus everything {@link documentEnv}'s options used to carry that
+ * only the generator ever read.
+ *
+ * @remarks
+ * Generic over `S`, the exact schema type {@link documentEnv} infers from its `schema` argument --
+ * this is what makes `variables` below a closed, checked map (a typo'd or renamed key is a
+ * compile error, not a silent no-op) rather than an open `Record<string, VariableDocs>` any string
+ * would satisfy. `S` defaults to the widest possible schema so this type is still nameable on its
+ * own (e.g. in a helper function's own parameter type) without narrowing to one specific contract.
+ */
+export interface ContractDocs<S extends EnvSchema = EnvSchema> {
+    /** Overrides the auto-generated label used in generated docs. Purely cosmetic. Wins over `createEnv()`'s own `name` option, which in turn wins over the exported binding name. */
+    name?: string;
+    /** Groups this contract under a heading in the generated docs' feature catalog. */
+    category?: string;
+    /** The generator throws if two *active* contracts declare the same `exclusiveGroup` -- use it to mark interchangeable features (e.g. two database backends) as mutually exclusive. */
+    exclusiveGroup?: string;
+    /** When `false`, this contract is excluded from the generated manifest, docs' required section, and exclusiveGroup checks -- it still appears, marked disabled, in the feature catalog. Defaults to `true`. */
+    active?: boolean;
+    /** Default owner for every variable in this contract that doesn't set its own `owner`. */
+    owner?: string;
+    /** Default sensitivity for every variable in this contract that doesn't set its own `sensitivity` -- see {@link VariableDocs.sensitivity} for why this is an open `string`. */
+    sensitivity?: string;
+    /** Whole-contract/feature sunset date, ISO date string. */
+    expiresAt?: string;
+    /** Marks this whole contract/feature as being phased out. Independent of `active` (on/off, not a phase-out signal). */
+    deprecated?: boolean;
+    /** Why this contract is deprecated, and/or what to use instead. Only meaningful alongside `deprecated: true`. */
+    deprecatedReason?: string;
+    /** Default reason this contract's variables' values are collected/used -- see {@link VariableDocs.purpose}. */
+    purpose?: string;
+    /** Default legal basis for this contract's variables -- see {@link VariableDocs.legalBasis}. */
+    legalBasis?: string;
+    /** Default retention policy for this contract's variables -- see {@link VariableDocs.retention}. */
+    retention?: string;
+    /** Default data residency for this contract's variables -- see {@link VariableDocs.dataResidency}. */
+    dataResidency?: string | string[];
+    /** Default audit-required assertion for this contract's variables -- see {@link VariableDocs.auditRequired}. */
+    auditRequired?: boolean;
+    /** Arbitrary contract-level documentation (e.g. `runbook`), rendered alongside this feature -- see {@link VariableDocs.metadata}. */
+    metadata?: Record<string, unknown>;
+    /**
+     * Per-variable documentation, keyed by variable name -- keys are checked against `S`'s own keys
+     * at compile time, so documenting a variable that was renamed or removed from `schema` (or a
+     * plain typo) is a type error here, not a silently-ignored entry the generator would otherwise
+     * have to report as "stale" after the fact. A schema key absent from `variables` entirely is
+     * still valid (not every variable needs documentation) and is reported as undocumented by the
+     * generator, exactly as before.
+     */
+    variables?: {
+        readonly [K in keyof S]?: VariableDocs;
+    };
+}
+/**
+ * Documents a schema for the generator: explains values, assigns ownership,
+ * and describes lifecycle, feeding the generated docs artifact and
+ * `.env.example`. Pass it the *same* schema object given to {@link createEnv}, so
+ * the generator can statically link the two and verify every variable is
+ * documented -- and so TypeScript can check `docs.variables`' keys against
+ * `schema`'s own keys, the same object identity doing double duty for both
+ * the generator's static link and the type checker's.
+ *
+ * @remarks
+ * A no-op at runtime by design -- nothing passed here is retained anywhere,
+ * and this can never throw, no matter how malformed `schema`/`docs` are.
+ * Calling it is entirely optional: {@link createEnv} works identically whether or
+ * not a matching `documentEnv` call exists. The real "is everything
+ * documented?" check, and every artifact this data drives (the docs
+ * artifact's ownership matrix, dependency graph, lifecycle report, and
+ * security review; `.env.example`'s comments), runs entirely inside
+ * {@link build.generateEnvManifest}'s static analysis -- this function's only job at
+ * runtime is to exist as a safe, harmless marker the AST parser can find,
+ * and to give you type-checked argument shapes while writing it.
+ *
+ * `S` is inferred from `schema`, never written out by hand -- pass the
+ * schema object literal (or a `const`-inferred reference to it) directly for
+ * the strongest inference; an explicitly-widened `schema: EnvSchema`
+ * annotation loses the per-key literal type and falls back to accepting any
+ * string key in `docs.variables`, same as before this generic existed.
+ */
+export declare function documentEnv<S extends EnvSchema>(schema: S, docs: ContractDocs<S>): void;
+export {};
+//# sourceMappingURL=document.d.ts.map

package/dist/.dts/runtime/document.d.ts.map

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

package/dist/.dts/runtime/errors.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Every error type here is constructed only from: the variable name, the
+ * declaring contract's name, the failure kind, and a message string that the
+ * *developer's own* processor/validator produced. Raw or processed environment
+ * values are never read into an error -- see the Security section in the README.
+ *
+ * Documentation (description, owner, etc.) never appears here, even when a
+ * {@link documentEnv} call exists for this variable -- `documentEnv` is
+ * build-time-only and its data is never retained anywhere {@link validateEnv}
+ * could read it back out. This is a deliberate consequence of keeping the
+ * runtime minimal, not an oversight.
+ */
+/** One variable's processing or validation failure, as recorded by {@link validateEnv}. */
+export interface VariableFailure {
+    /** The schema key that failed. */
+    readonly variable: string;
+    /** The declaring contract's `name` (see {@link CreateEnvOptions}). */
+    readonly contractName: string;
+    /** `import.meta.url` (or similar) passed to `createEnv`'s `source` option, if any. Falls back to `contractName` when absent. */
+    readonly source: string | undefined;
+    /** Which stage produced the failure. */
+    readonly kind: "processor" | "validator";
+    /** The error message from the developer's own processor/validator, or the thrown error's message. */
+    readonly message: string;
+}
+/**
+ * Thrown by {@link validateEnv} when one or more variables fail processing or
+ * validation. Aggregates every failure across every contract in the batch --
+ * the caller sees the whole picture in one error, not one-at-a-time.
+ *
+ * @remarks
+ * `code` is a stable, Stable-tier discriminant for programmatic handling --
+ * prefer it over `.name`/`instanceof` when a message-independent switch is needed.
+ */
+export declare class EnvValidationError extends Error {
+    /** Stable discriminant for programmatic handling; always `"ENV_VALIDATION_FAILED"`. */
+    readonly code = "ENV_VALIDATION_FAILED";
+    /** Every variable failure across every contract in the batch. */
+    readonly failures: readonly VariableFailure[];
+    constructor(failures: readonly VariableFailure[]);
+}
+/**
+ * Thrown when a contract's value is accessed via property access before
+ * {@link validateEnv} has completed successfully for it.
+ *
+ * @remarks
+ * `code` is a stable, Stable-tier discriminant for programmatic handling --
+ * prefer it over `.name`/`instanceof` when a message-independent switch is needed.
+ */
+export declare class EnvNotReadyError extends Error {
+    /** Stable discriminant for programmatic handling; always `"ENV_NOT_READY"`. */
+    readonly code = "ENV_NOT_READY";
+    constructor(contractName: string, key: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/.dts/runtime/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/runtime/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,2FAA2F;AAC3F,MAAM,WAAW,eAAe;IAC9B,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,sEAAsE;IACtE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,gIAAgI;IAChI,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,WAAW,CAAA;IACxC,qGAAqG;IACrG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAwBD;;;;;;;;GAQG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,uFAAuF;IACvF,QAAQ,CAAC,IAAI,2BAA0B;IACvC,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAA;gBAEjC,QAAQ,EAAE,SAAS,eAAe,EAAE;CAMjD;AAED;;;;;;;GAOG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,mBAAkB;gBAEnB,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;CAS9C"}

package/dist/.dts/runtime/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * env-cap runtime entry point.
+ *
+ * Zero dependencies, isomorphic (no `fs`, no `process` other than the values
+ * the developer passes in). Handles processing, validation, caching, and
+ * typed access only -- discovery and manifest generation live in
+ * `env-cap/build` and are never imported from here.
+ *
+ * `documentEnv` is exported from here, not `env-cap/build`, even though
+ * it exists purely for documentation: it's meant to be called inline in the
+ * same schema file as `createEnv`, which is ordinary runtime code that may
+ * end up in any bundle (including a browser one). It must be exactly as
+ * cheap and safe to import as `createEnv` -- see `document.ts`.
+ */
+export type { CreateEnvOptions, DefaultValue, EnvContract, EnvDefinition, EnvSchema, InferEnvValue, Processor, RawEnv, validateEnvOptions, validateEnvResult, Validator, } from "./types.js";
+export { createEnv } from "./create.js";
+export { documentEnv } from "./document.js";
+export type { ContractDocs, VariableDocs } from "./document.js";
+export { EnvNotReadyError, EnvValidationError } from "./errors.js";
+export type { VariableFailure } from "./errors.js";
+export { isEnvContract } from "./registry.js";
+export { resetEnvCache } from "./reset.js";
+export { validateEnv } from "./validate.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/.dts/runtime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,aAAa,EACb,SAAS,EACT,aAAa,EACb,SAAS,EACT,MAAM,EACN,kBAAkB,EAClB,iBAAiB,EACjB,SAAS,GACV,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC/D,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAClE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA"}

package/dist/.dts/runtime/registry.d.ts

@@ -0,0 +1,12 @@
+import type { ContractInternals } from "./types.js";
+/** Associates a contract object with its internal identity/schema. Called once, by `createEnv`. */
+export declare function registerContract(contract: object, internals: ContractInternals): void;
+/**
+ * Looks up a contract's internal identity/schema.
+ *
+ * @throws {TypeError} If `contract` wasn't returned by `createEnv` (and so was never registered).
+ */
+export declare function getContractInternals(contract: object): ContractInternals;
+/** Type guard: `true` when `value` was created by `createEnv` (i.e. is a registered contract). */
+export declare function isEnvContract(value: unknown): value is object;
+//# sourceMappingURL=registry.d.ts.map

package/dist/.dts/runtime/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/runtime/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAUnD,mGAAmG;AACnG,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,iBAAiB,GAAG,IAAI,CAErF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CASxE;AAED,kGAAkG;AAClG,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAmB7D"}

package/dist/.dts/runtime/reset.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Clears cached validation state. Intended for tests and dev tooling (e.g.
+ * `beforeEach(() => resetEnvCache())` in a test suite that re-validates with
+ * different fixture values per test) -- production applications validate
+ * once at startup and should not normally call this.
+ */
+export declare function resetEnvCache(): void;
+//# sourceMappingURL=reset.d.ts.map

package/dist/.dts/runtime/reset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reset.d.ts","sourceRoot":"","sources":["../../../src/runtime/reset.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAEpC"}