@arki/env 0.0.9 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,196 @@
+# @arki/env
+
+## 0.2.0
+
+### Minor Changes
+
+- 307dcf6: Encrypted env files in the dotenvx 2.x format. New `@arki/env/node`: `loadEnvFiles()` reads `.env.<environment>` and `.env.local` from the repository root down to the working directory, decrypts `encrypted:` values (via `eciesjs`, byte-compatible with dotenvx), resolves `op://`, `infisical://` and `doppler://` references, and writes what the real environment does not set into it (real values win; differing ones are reported as shadowed). Also the codec and file edits behind `dot env`. New side-effect entry `@arki/env/node/register`. `@arki/env/core` adds `describeEnv`, `isSecretSchema` and `SECRET_SCHEMA`, and `defineEnv` now refuses a value that is still `encrypted:` instead of accepting ciphertext as a string. New codes `ARKI_ENV_FILES_E001`–`E003`.
+- a7a4a9d: Fix the foundation findings of the T08 review.
+
+  - `@arki/log`: `maskSecrets` and `otelSink` handle an object that contains itself (the cycle becomes `[Circular]`) instead of dropping the record. A `.to('name')` logger whose channel is not defined no longer throws into the caller at log time; the fault is reported once and the channel is skipped. `file()` throws a coded `LogError` (`ARKI_LOG_E006`) when it cannot open its path.
+  - `@arki/async`: `debounce` and `throttle` take an `onError` option. An error thrown by the callback, or a promise it returns that rejects, goes there. Without it the error is rethrown from a microtask. The schedule stays consistent and a leading call never throws into the caller.
+  - `@arki/env`: `rotateEnvFiles` returns an `InvalidInput` failure for an empty list or files of two environments (it threw a plain `Error`). The default `onValidationError` of `defineEnv` throws an `UnexpectedFailure` that carries the new `env.invalid_environment` failure (`InvalidEnvironment`).
+
+- 818fd9c: The Dot adapter moved from `@arki/env/dot` to `@arki/dot/env`. `@arki/env` drops its `@arki/dot` peer; `@arki/dot` depends on `@arki/env`. `@arki/env/core` exports `formatIssues`. Migration: `packages/env/docs/upgrades/0.1.0-to-0.2.0.md`.
+- 0511f4a: Return precise canonical env node outcomes, sanitize provider diagnostics, validate distinct public/private key domains and preserve recovery keys across partial rotation. Share bounded load deadlines and cooperative cancellation with provider reads, and instrument owned node/provider operations through OpenTelemetry without installing an SDK. Migrate Dot env commands and database preparation to handle the returned outcomes.
+
+  Keep explicit zero/empty defaults and report JSON parsing/output rejection through schema issues. Storage and crypto remain dotenvx-compatible; see `@arki/env/docs/upgrades/typed-node-outcomes.md`.
+
+  no demo impact: node env operations are exercised through the CLI and package tests.
+
+- cd969bd: Breaking: `@arki/env/contracts` is now `@arki/env/presets`. `contracts` is `presets` (also from `@arki/env` and `@arki/env/core`), and `commonContracts`, `urlContracts`, `parseContracts` are `commonPresets`, `urlPresets`, `parsePresets`. The validators are unchanged. See `docs/upgrades/0.1.0-to-0.2.0.md`.
+
+### Patch Changes
+
+- 1e47612: `Lazy<T>` and `resolveLazy` move from `@arki/ts` to `@arki/dot/plugin` as `Deferred<T>` and `resolveDeferred`. They are the "value now, or a thunk the adapter calls at boot" shape that Dot adapters accept, and the old name clashed with Dot's own `Lazy<Value, Cleanup>` service handle. Behaviour is unchanged. `@arki/ts` no longer exports them; to upgrade, import `Deferred` and `resolveDeferred` from `@arki/dot/plugin`.
+
+  `@arki/http` (`port`) and `@arki/kv` (`kv()`, `kv.optional()`) now type their deferred options as `Deferred<T>`, the same shape as before, and no longer depend on `@arki/ts`. `@arki/env` drops an `@arki/ts` dependency it never imported.
+
+  demo impact: none (neither demo imports `Lazy` or `resolveLazy`).
+
+## 0.1.0
+
+### Minor Changes
+
+- 1e15576: `defineEnv()` `server`, `client` and `shared` take records of any Standard Schema (Zod, Valibot, ArkType, hand-written), not only `ZodType`; values are typed as each schema's output.
+  `@arki/env/dot`: `EnvDotOptions`, `EnvServices` and `env()` take `Record<string, StandardSchemaV1>` instead of `Record<string, ZodType>`.
+- 75d6fb9: **Validation now runs in production by default.** `defineEnv` used to skip validation whenever `NODE_ENV !== 'development'`, so an app without an explicit `skipValidation` booted production on an unchecked config. The default now skips only when `CI` is set (Docker build stages) or during `lint` runs, the same rule most apps already passed by hand. Apps that set `options.skipValidation` are unaffected.
+
+  New `secret(schema)`, `reveal(value)` and `Redacted` (from `@arki/env/core`): a secret variable becomes a `Redacted` value that prints as `[redacted]` in logs, JSON, template strings and `util.inspect`, and is read with a deliberate `reveal(env.KEY)`. `reveal` also accepts the raw string, for runs where validation is skipped.
+
+- cc7facf: Breaking: `defineEnv` now validates in every environment. `CI` and `lint` runs no longer skip validation. The only implicit opt-out is `SKIP_ENV_VALIDATION=1` (exactly `1`); set it only in build stages that run without secrets. `options.skipValidation` still overrides it. The `@arki/env/dot` plugin now validates at boot and fails with `ARKI_ENV_PLUGIN_E001` (new `ENV_PLUGIN_ERROR_CODES`), and `EnvServices['env']` is derived from `defineEnv` without a cast.
+- a67cd66: `secret()` takes any Standard Schema (zod, valibot, arktype, hand-written) and returns a Standard Schema, not a zod schema. `.optional()` is still there: it accepts a missing variable and leaves `undefined` unwrapped. The result no longer has zod methods such as `.parse`; use `secret(schema)['~standard'].validate(value)`.
+
+  A rejected secret's issues keep their path but get a fixed message, because some validators (valibot) repeat the received value in theirs and `defineEnv` logs issues.
+
+### Patch Changes
+
+- 064e096: Make failure the acyclic validation foundation. Schema parsing now returns exact typed validation failures, and failure revival returns typed protocol/validator defects instead of throwing. Add validated versioned JSON envelopes; retain legacy envelope reads while rejecting non-JSON data and changing output transforms. oRPC error maps validate output-only wire data.
+
+  Migrate consumers to check failures, propagate them through Journal event/write/replay and queue/mail operations, and use explicit exception bridges at foreign callbacks. Journal rejects invalid event entries before inserting them. See `@arki/failure/docs/upgrade-typed-validation.md` for breaking API and stored-data migration details.
+
+- 652eb4b: `env()`, `resilience()`, `auth()`, `journal()`, `journalProjections()`, `queue()`, `durableScheduler()` and `outboxPlugin()` keep their plugin name in the type, so their handles carry `provider: 'env' | 'resilience' | …` instead of `string` and the feature builder's handle-identity checks apply around them. The three queue plugins gain an overload: with no `name` option the type carries the default name (`'queue'`, `'durable-scheduler'`, `'outbox'`); with `name: 'jobs'` it carries `'jobs'`.
+- cbefc52: Dot plugins no longer pass a hard-coded `version` (the field was removed from `@arki/dot`).
+- 5bc6390: `env()` publishes through a `provides` factory, so `envPlugin.provides.env` is a typed handle before boot (`@arki/dot` plugin handles).
+- fd18765: `defineEnv` reads `globalThis.process?.env` instead of the bare `process` global, so it no longer throws a ReferenceError on engines without `process` (React Native Hermes, browsers). It still reads nothing at import. Pass `runtimeEnv` on those engines. Added the library lint preset and a cross-runtime smoke test.
+- fe5a391: README follows the docs standard (install, quick start, limits, failure behaviour), with `llms.txt`, an agent guide, `AGENTS.md`, `test:docs` and the 0.0.11 to 0.1.0 upgrade guide. `ARKI_ENV_PLUGIN_E001` gains `@fix` and `@verify` tags.
+
+  no demo impact: documentation and doc-example changes only, runtime behaviour unchanged
+
+- Updated dependencies [dcf2cef]
+- Updated dependencies [afecc7a]
+- Updated dependencies [5bc6390]
+- Updated dependencies [899d0a9]
+- Updated dependencies [ce8d707]
+- Updated dependencies [92b38ed]
+- Updated dependencies [9a4babb]
+- Updated dependencies [80a4aa5]
+- Updated dependencies [232d3e8]
+- Updated dependencies [69d054f]
+- Updated dependencies [cbefc52]
+- Updated dependencies [7b19289]
+- Updated dependencies [923124f]
+- Updated dependencies [5721742]
+- Updated dependencies [01400a0]
+- Updated dependencies [0ab11d8]
+- Updated dependencies [a531063]
+- Updated dependencies [9b35520]
+- Updated dependencies [5721742]
+- Updated dependencies [232d3e8]
+- Updated dependencies [9192d0e]
+- Updated dependencies [3230f02]
+- Updated dependencies [232d3e8]
+- Updated dependencies [232d3e8]
+- Updated dependencies [932c9e4]
+- Updated dependencies [232d3e8]
+- Updated dependencies [cc656e3]
+- Updated dependencies [ff8e384]
+- Updated dependencies [ce8d707]
+- Updated dependencies [847f025]
+- Updated dependencies [232d3e8]
+- Updated dependencies [d9864f3]
+- Updated dependencies [742f4c3]
+- Updated dependencies [115aa87]
+- Updated dependencies [6e4d7da]
+- Updated dependencies [8b3cc80]
+  - @arki/dot@0.7.0
+
+## 0.0.11
+
+### Patch Changes
+
+- @arki/dot@0.6.1
+
+## 0.0.10
+
+### Patch Changes
+
+- Updated dependencies [228b4f5]
+- Updated dependencies [9fa13ce]
+  - @arki/dot@0.6.0
+
+## 0.0.9
+
+### Patch Changes
+
+- 91efd52: Reading a value from a `defineEnv()` env is faster once the env is in regular use. After 64 reads, an env whose values are private to it (validated on the server, or skipped with the runtime env `defineEnv` built itself) copies its values into the lazy object and reads them directly, instead of going through two proxies on every read. Writes and deletes through the env update the copy too. An env over your own `runtimeEnv` with validation skipped still reads it live.
+- Updated dependencies [0685dfa]
+- Updated dependencies
+- Updated dependencies [2854df5]
+  - @arki/dot@0.5.0
+
+## 0.0.8
+
+### Patch Changes
+
+- Dependency refresh: `@t3-oss/env-core` ^0.13.11, `zod` 4.6.5. No API changes.
+
+## 0.0.7
+
+### Patch Changes
+
+- Lazy primitives family + client-surface hardening.
+
+  - `@arki/ts`: new `once()` (zero-arg memo; memoizes `undefined`, sync throws retry, promises shared), hardened `lazyObject()` (`set`/`deleteProperty`/`getPrototypeOf` traps — writes land on the real instance, `instanceof` answers truthfully), new `Lazy<T>`/`resolveLazy` deferred-config vocabulary, and a `./testing` entry with `expectImportPure()` (subprocess import-purity harness).
+  - `@arki/env`: `defineEnv` now delegates its lazy proxy to `lazyObject` (single trap implementation).
+  - `@arki/kv`: `kv()` accepts a whole-options thunk — `kv(() => ({ url: env.REDIS_URL }))` — keeping declarations import-pure; per-field `url` thunk kept for compatibility.
+  - `@arki/http`: `port` adopts `Lazy<number>`; documented why `bundles`/`features` tokens cannot defer (declaration-time wiring).
+  - `@arki/contracts`: `browser` exports condition serves a zod-only build (no `drizzle-orm`) to client bundlers; table wrappers are node-only and fail loudly at bundle time from browser code.
+  - `@arki/db` / `@arki/event-sourcing`: republished to align the `@arki/dot` peer range with 0.4.0.
+
+- Updated dependencies
+- Updated dependencies
+  - @arki/dot@0.4.0
+  - @arki/ts@0.0.3
+
+## 0.0.6
+
+### Patch Changes
+
+- Updated dependencies [4b1c59f]
+  - @arki/dot@0.3.0
+
+## 0.0.5
+
+### Patch Changes
+
+- Updated dependencies [48a8733]
+  - @arki/dot@0.2.0
+
+## 0.0.4
+
+### Patch Changes
+
+- Updated dependencies [9871fce]
+  - @arki/dot@0.1.3
+
+## 0.0.3
+
+### Patch Changes
+
+- Ship TypeScript source in the npm tarball (`src/**` added to `files`). npm installs and the read-only GitHub mirrors now carry the original `.ts` source alongside compiled `dist/` — better debuggability on the experimental track. No runtime changes.
+- Updated dependencies
+  - @arki/dot@0.1.2
+
+## 0.0.2
+
+### Patch Changes
+
+- DOT v2 pip contract — typed dependency injection (BREAKING on the experimental track).
+
+  `pip()` replaces `defineDotPip`: pips declare consumed services as `needs` shapes of type witnesses (`service<T>()` app-local, `token<T>()('key')` cross-package) and hooks destructure them fully typed; provides are inferred from `boot`'s return value. `.use()` is compile-time guarded (unsatisfied needs, type mismatches, wire-key collisions fail at the call site). Declaration order is boot order — the topological sort and name-based `dependencies` are gone; manifest dependency edges are observed from actual wiring. `rename(pip, map, name?)` is the multi-instance primitive, replacing the adapters' silent last-writer-wins `name` options. `lazy(init, { dispose? })` defers expensive opens behind a memoized single-flight `Lazy<T>` handle the kernel auto-disposes; `service.lazy<T>()` lifts eager or lazy providers into a uniform handle. The four `/dot` adapters (`@arki/env`, `@arki/kv`, `@arki/db`, `@arki/event-sourcing`) are migrated to the new contract.
+
+- Updated dependencies
+  - @arki/dot@0.1.1
+
+## 0.0.1
+
+### Initial release
+
+- First public publication on npm (experimental track) — 2026-05-21.
+
+  Part of **Wave 1**, the ARKI foundation: zero-dependency utilities and runtime primitives shipped together because every downstream wave (DOT kernel, infrastructure adapters) consumes them. Wave 1 packages: `assert`, `clock`, `contracts`, `date`, `env`, `log`, `resilience`, `slugify`, `string`, `ts`.
+
+  **Why 0.0.x, not 1.0.0**: ARKI is on an experimental track. The 0.0.x prefix is an honest signal — APIs may change without semver discipline until the kernel is field-tested. The release scorecard (metadata, privacy, dependencies, build-output, packlist, docs, fixtures, DOT gates, agent-native gates) is satisfied at this version; the gate certifies _the artifact_, not _API stability_. Stability is earned through reuse, not declared at first publication.
+
+  Wave 2 (`@arki/dot`) and Wave 3 (`@arki/db`, `@arki/kv`, `@arki/event-sourcing`) publish in subsequent releases once their inter-package transitive resolution against the public npm registry is verified.

package/README.md

@@ -1,80 +1,249 @@
 # @arki/env
 
-Type-safe environment variable parsing for ARKI. `defineEnv()` is a thin wrapper around [`@t3-oss/env-core`](https://env.t3.gg/) with Zod contracts for common variable shapes — ports, URLs, comma-separated lists, JSON, and more.
+Type-safe environment variables for ARKI. `defineEnv()` wraps [`@t3-oss/env-core`](https://env.t3.gg/). It validates on the first read and returns a typed object. Any [Standard Schema](https://standardschema.dev) works: Zod, Valibot, ArkType or a hand-written `~standard` object.
 
-## Installation
+## Install
 
 ```sh
-npm install @arki/env
-# or
 bun add @arki/env
-# or
-pnpm add @arki/env
 ```
 
-## Usage
+## Quick start
 
-### `defineEnv`
+Declare the variables once. Read them anywhere. A bad value throws on the first read, never at import.
 
-```ts
+```ts run expect
 import { defineEnv } from '@arki/env/core';
-import { contracts } from '@arki/env/contracts';
+import { presets } from '@arki/env/presets';
 
-export const env = defineEnv({
+const env = defineEnv({
   server: {
-    NODE_ENV: contracts.nodeEnv(),
-    PORT: contracts.port(3000),
-    DATABASE_URL: contracts.url(),
-    LOG_LEVEL: contracts.string('info'),
+    PORT: presets.port(3000),
+    DATABASE_URL: presets.url(),
   },
+  runtimeEnv: { PORT: '8080', DATABASE_URL: 'https://db.example.com' },
+});
+
+console.log(env.PORT, typeof env.PORT);
+console.log(env.DATABASE_URL);
+```
+
+```text
+8080 number
+https://db.example.com
+```
+
+Leave out `runtimeEnv` in a server app. `defineEnv` then reads `globalThis.process?.env` on the first access.
+
+## When not to use this
+
+- You need a config file, layered sources or hot reload. This package reads environment variables only.
+- Your validator is asynchronous. Validation is synchronous.
+- You need the secret to stay hidden from code in the same process. `secret()` stops accidents in logs. It is not encryption.
+
+## Runtime support
+
+`@arki/env/core` and `@arki/env/presets` run on Node, Bun, Deno, browsers and React Native (Hermes). Nothing reads the environment at import. On an engine with no `process`, pass `runtimeEnv`. A browser cannot read server keys, so declare client keys (`clientPrefix`) for code that ships to it. The Dot adapter lives in `@arki/dot/env`. `bun run test:runtimes` runs a smoke test of the built package on each runtime. The Hermes leg needs `HERMES_BIN`.
+
+`@arki/env/node` (encrypted env files) runs on Node, Bun and Deno only. It reads files and starts provider CLIs.
+
+## Public imports
+
+- `@arki/env/core`: `defineEnv`, `secret`, `reveal`, `Redacted`, `describeEnv`, `isSecretSchema`, `formatIssues`.
+- `@arki/env/presets`: `presets` and the per-category namespaces `commonPresets`, `urlPresets`, `parsePresets`.
+- `@arki/env`: re-exports `presets`.
+- `@arki/env/node`: `loadEnvFiles`, `secretValues`, `formatEnvFilesErrors`, `ENV_FILES_ERROR_CODES`, the codec (`encryptValue`, `decryptValue`, `generateKeypair`, `parseEnv`, …), the file edits behind `dot env`, `findPrivateKey` and `DEFAULT_RESOLVERS`.
+- `@arki/env/node/register`: a side-effect import that loads the env files into `process.env`.
+
+## Secrets
+
+Wrap a secret's schema in `secret(...)`. The variable becomes a `Redacted` value. It prints as `[redacted]` in logs, JSON, template strings and `console.log`. The compiler will not pass it where a string is expected. Read it with `reveal(...)` at the one place that needs it. For an optional secret, call `.optional()` on the result. A missing variable then stays `undefined`.
+
+```ts run expect
+import { z } from 'zod';
+
+import { defineEnv, reveal, secret } from '@arki/env/core';
+
+const env = defineEnv({
+  server: { STRIPE_KEY: secret(z.string().min(1)) },
+  runtimeEnv: { STRIPE_KEY: 'sk_live_123' },
 });
 
-console.log(env.PORT); // number
-console.log(env.DATABASE_URL); // string (validated URL)
+console.log(String(env.STRIPE_KEY));
+console.log(reveal(env.STRIPE_KEY));
+```
+
+```text
+[redacted]
+sk_live_123
+```
+
+`reveal` also accepts the raw string, because schemas do not run when validation is skipped.
+
+## Encrypted env files
+
+Commit `.env.<environment>` files with their secrets encrypted. The format is dotenvx 2.x, so the `dotenvx` CLI reads the same files. Each file holds a public key, so anyone can add a value. Only a holder of the private key can read one. The private key lives in `DOTENV_PRIVATE_KEY_<ENV>` (for `.env.production`: `DOTENV_PRIVATE_KEY_PRODUCTION`) or in the gitignored `.env.keys` file.
+
+Edit the files with `dot env` from `@arki/dot`:
+
+```sh
+dot env init                     # public key header + private key for .env.development
+dot env set STRIPE_KEY --stdin   # stored encrypted; the value never appears in argv
+dot env set PORT 3000 --plain    # refused when the schema declares PORT secret()
+dot env run -- bun run dev       # load, decrypt, run; secrets redacted when output is piped
+dot env check                    # CI gate: no tracked key file, no plaintext secret()
 ```
 
-`defineEnv` reads from `process.env`, validates against the Zod schemas in `server`, and returns a fully typed object. It skips validation when `CI` is set or `NODE_ENV !== 'development'` unless you override via `options.skipValidation`.
+Load the files once, at the top of a process. Use `dot env run -- <command>` (the app templates' `with-env` script does), or make `import '@arki/env/node/register'` the first import of an entry. Both write into `process.env`, because package envs such as `@arki/db/env` read it.
+
+- The real environment wins. A file never replaces a value that is already set; a different value is reported as shadowed.
+- The environment is `NODE_ENV`, else `development`. Files load from the repository root down to the working directory. A deeper folder wins, and `.env.local` wins over `.env.<environment>`. Under `test`, `.env.local` is skipped.
+- A value can be a reference: `op://vault/item/field`, `infisical://…` or `doppler://…`. The provider's CLI resolves it at load. A public key (`VITE_`, `NEXT_PUBLIC_`, `PUBLIC_`, `EXPO_PUBLIC_`) is never filled from a reference.
+- Keys that change how a process runs (`PATH`, `NODE_OPTIONS`, `LD_*`, TLS settings and more) are never loaded from a file.
+- A private key is needed only when a value needs it. A key already set in the environment needs no decryption.
+- `defineEnv` refuses a value that is still `encrypted:`, so ciphertext never passes as a string.
 
-### Contracts
+Mask loaded secrets in logs, wherever they appear:
 
-The `contracts` namespace bundles common variable shapes so you do not have to assemble them by hand. The categories:
+```ts skip="needs encrypted env files on disk"
+import { secretValues } from '@arki/env/node';
+import { configure, maskSecrets } from '@arki/log';
 
-- **Common**: `string`, `number`, `boolean`, `port`, `nodeEnv`.
-- **URLs**: `url`, `httpsUrl`, `postgresUrl`, `redisUrl`.
-- **Parsing**: `csv`, `json`, `keyValue`.
+configure({ processors: [maskSecrets(secretValues)] });
+```
 
-```ts
-import { contracts } from '@arki/env/contracts';
+| Code                      | Meaning                                                   |
+| ------------------------- | --------------------------------------------------------- |
+| `env.missing_private_key` | A file has encrypted values and no private key was found. |
+| `env.decryption_failed`   | A value did not decrypt with the key that was found.      |
+| `env.reference_failed`    | A reference could not be resolved by its provider CLI.    |
+
+Messages name the file and the key, never a value. `loadEnvFiles` returns `EnvFilesFailed` with these entries in `data.errors`; native file-read problems use `env.file_read_failed`. No entries are applied when loading fails. Raw provider errors and stderr stay in the failure's private cause.
+
+### Node file API
+
+These come from `@arki/env/node`. The codec functions work on text and never touch the disk. The file functions read and write, and return a failure (check `isFailure`) instead of throwing.
+
+| Export | What it does and when to use it |
+| --- | --- |
+| `encryptEnvFile(file, keys?)` | Encrypts plaintext values in place, for the listed keys or every value. Returns the keys it encrypted. Use it to import an old plain file. Returns `MissingPublicKey` when the file has no header. |
+| `decryptEnvFile(file, privateKeys, keys?)` | Writes values back as plaintext, for the listed keys or every value. Use it for a one-off migration, never on a tracked file you plan to commit. |
+| `rotateEnvFiles(...)` | Gives every file of one environment a new keypair and encrypts it again. It decrypts everything first, so a wrong key changes nothing. Returns `RotationIncomplete` if it stops half way. |
+| `publicKeyIn(file)` | Reads the public key from the file header, or `undefined` when there is none. Use it to check that a file was initialised. |
+| `envHeader(fileName, publicKey)` | Builds the dotenvx header text (banner, public key, file line). `initEnvFile` uses it; call it to write a header yourself. |
+| `keyNamesFor(fileName)` | Gives the key variable names for a file: `.env.production` gives `DOTENV_PUBLIC_KEY_PRODUCTION` and `DOTENV_PRIVATE_KEY_PRODUCTION`. |
+| `isKeyName(key)` | True for `DOTENV_PUBLIC_KEY*` and `DOTENV_PRIVATE_KEY*`. Use it to skip key lines when you list app values. |
+| `isEncrypted(value)` | True for a value that starts with `encrypted:`. Use it to tell ciphertext from plaintext. |
+| `envValues(document)` | Every key of a parsed file with its last value, in first-seen order. |
+| `readEnvValue(document, key)` | The last value of one key in a parsed file, or `undefined`. |
+| `setEnvValue(text, key, value)` | Returns the text with the key set. It rewrites an existing line in place and appends a new key. Other lines stay as written. |
+| `removeEnvValue(text, key)` | Returns the text without any line that sets the key. |
+| `keysFileCandidates(file, root)` | The `.env.keys` paths searched for a file, nearest first. |
+| `findRoot(cwd)` | The nearest folder above `cwd` that has `.git`, else one with a `workspaces` package.json, else `cwd`. This is where file loading stops. |
+| `envDirs(root, cwd)` | The folders from `root` down to `cwd`, root first. Files load in this order, so a deeper folder wins. |
+| `referenceScheme(value, resolvers)` | Returns the scheme (`op`, `infisical`, `doppler`) when the value is a registered reference, else `undefined`. Unknown URLs stay plain values. |
+| `envPublicKeySchema`, `envPrivateKeySchema` | Standard Schemas that check a secp256k1 key and brand it as `EnvPublicKey` or `EnvPrivateKey`. They never repeat the key in an issue. `parsePublicKey` and `parsePrivateKey` call them. |
+
+### Node failures
+
+| Failure | Code | When it is returned | How to fix it |
+| --- | --- | --- | --- |
+| `MissingPublicKey` | `env.missing_public_key` | You tried to encrypt into a file that has no public key header. `data.file` names it. | Initialise the file first (`dot env init`, or `initEnvFile`). |
+| `MissingPrivateKey` | `env.missing_private_key` | A file has encrypted values and no private key is available. `data.file` names it. | Restore the key from its backup: set `DOTENV_PRIVATE_KEY_<ENV>` or restore `.env.keys`. |
+| `ReferenceFailed` | `env.reference_failed` | A provider CLI (`op`, `infisical`, `doppler`) rejected a read. `data.scheme` names the provider. HTTP status 502. | Check that the CLI is installed and signed in, and that the reference is right. The raw cause stays private. |
+
+## Presets
+
+The `presets` namespace holds common variable shapes:
+
+- Common: `string`, `number`, `boolean`, `port`, `nodeEnv`, `logLevel`.
+- URLs: `url`, `databaseUrl`, `redisUrl`.
+- Parsing: `json(schema)`, `csvArray(itemSchema)`, `csvSet(itemSchema)`.
+
+```ts run expect
+import { z } from 'zod';
+
+import { defineEnv } from '@arki/env/core';
+import { presets } from '@arki/env/presets';
 
 const env = defineEnv({
   server: {
-    ALLOWED_ORIGINS: contracts.csv(),       // 'a,b,c' → ['a', 'b', 'c']
-    FEATURE_FLAGS: contracts.json(),         // JSON-parsed
-    SERVICE_TAGS: contracts.keyValue(),      // 'a=1,b=2' → { a: '1', b: '2' }
+    ALLOWED_ORIGINS: presets.csvArray(z.string()),
+    FEATURES: presets.json(z.object({ beta: z.boolean() })),
   },
+  runtimeEnv: { ALLOWED_ORIGINS: 'a,b,c', FEATURES: '{"beta":true}' },
+});
+
+console.log(env.ALLOWED_ORIGINS);
+console.log(env.FEATURES);
+```
+
+```text
+[ "a", "b", "c" ]
+{
+  beta: true,
+}
+```
+
+## Failure behaviour
+
+`defineEnv` throws an `Error` on the first read of a bad environment. The message starts with your `name` and lists one `path: message` line per issue. The thrown error is an `UnexpectedFailure` that carries the `InvalidEnvironment` failure (code `env.invalid_environment`, exported from `@arki/env/core`), so a catcher can match on the code. Set `options.onValidationError` to throw something else.
+
+```ts run expect
+import { defineEnv } from '@arki/env/core';
+import { presets } from '@arki/env/presets';
+
+const env = defineEnv({
+  server: { PORT: presets.port(), DATABASE_URL: presets.url() },
+  runtimeEnv: { PORT: 'abc' },
 });
+
+try {
+  console.log(env.PORT);
+} catch (error) {
+  console.log(error instanceof Error ? 'invalid environment' : 'unknown');
+}
 ```
 
-## API
+```text
+invalid environment
+```
+
+The Dot adapter (`env()` from `@arki/dot/env`) validates at boot. A bad environment stops `boot()` with `ARKI_ENV_PLUGIN_E001`. Its `remediation` tells you to set the listed variables. `dot explain` never validates.
+
+Handle it by fixing the variables. Do not catch the error and continue with defaults.
+
+Node execution is a separate contract. Codec, filesystem and provider operations return exact canonical failures from `@arki/failure`; check `isFailure(result)` before using a result. Key generation returns a keypair or `KeyGenerationFailed`; encryption returns text or `EncryptionFailed`; decryption returns text or `DecryptionFailed`; an unrepresentable dotenv value returns `UnrepresentableValue`. File operations return `FileReadFailed`, `FileWriteFailed` and their precise missing-key/crypto outcomes. Native errors remain private causes, never public messages.
 
-- `@arki/env/core`
-  - `defineEnv(config)` — validate `process.env` and return a typed object.
-- `@arki/env/contracts`
-  - `contracts` — flattened namespace of all built-in Zod contracts.
-  - `commonContracts`, `urlContracts`, `parseContracts` — per-category namespaces.
-- `@arki/env`
-  - Re-exports `contracts` from `@arki/env/contracts`.
+Parse external keys with `parsePublicKey` / `parsePrivateKey`. Their schemas create distinct `EnvPublicKey` and `EnvPrivateKey` types; a private key cannot be passed where a public key is required. Invalid keys return canonical schema failures without echoing their bytes.
+
+`loadEnvFiles({ signal, timeoutMs })` returns a report, `EnvFilesFailed`, `EnvCancelled` or `EnvDeadline`. Its default 30-second budget is shared by all reference reads. Synchronous provider callbacks receive the remaining budget and signal; cancellation is checked between calls. A synchronous syscall cannot be interrupted by a JavaScript abort handler while the event loop is blocked. Native provider subprocesses enforce their remaining timeout. `register` bridges these outcomes to a boot exception by explicit import.
+
+Rotation first atomically stores a comma-separated list containing the new and previous private keys in the root and every existing candidate local key store. Staging all stores finishes before ciphertext changes, preserving nearest-store precedence. This is the existing dotenvx multi-key format. It then replaces and reads back every env file before retiring the previous keys. `RotationIncomplete` identifies the recovery key store and committed count; keep that store and retry with it. Both generations remain usable after a partial rotation. Writes use exclusive temp files plus rename; this protects process interruption, not a power-loss durability guarantee.
+
+Owned node loads/edits, filesystem reads/writes and provider reads emit default OpenTelemetry spans and duration metrics through the API. No SDK is installed and no export I/O occurs without application configuration. Attributes contain bounded operation/outcome labels; paths, references, key bytes, values and raw causes are excluded. Pure definitions, schemas and local text/crypto transforms need no provider span.
+
+## Limits
+
+- Validation runs in every environment, production, CI and tests included. `NODE_ENV`, `CI` and `lint` never skip it.
+- The only implicit opt-out is `SKIP_ENV_VALIDATION=1`, exactly `1`. Use it only in build stages that run without secrets. `SKIP_ENV_VALIDATION=true` does not skip.
+- `options.skipValidation` overrides the variable in code.
+- Validation is synchronous. Validation is lazy, so a bad value shows at the first read, not at import.
+- With validation skipped, schemas do not run. Values are raw strings. `reveal` still works on them.
 
 ## Documentation
 
-`@arki/env` ships an optional `@arki/env/dot` adapter for the
-[`@arki/dot`](https://www.npmjs.com/package/@arki/dot) framework.
+- [Agent guide](docs/agent-guide.md): tasks and rules for agents.
+- [Upgrade 0.0.11 to 0.1.0](docs/upgrades/0.0.11-to-0.1.0.md): what broke and how to migrate.
+- [Upgrade 0.1.0 to 0.2.0](docs/upgrades/0.1.0-to-0.2.0.md): the Dot adapter moved to `@arki/dot/env`.
+- The Dot adapter `@arki/dot/env` publishes `env` through `provides`. Consumers write `needs: { env: envPlugin.provides.env }`. See the [`@arki/dot`](https://www.npmjs.com/package/@arki/dot) package for plugin authoring and lifecycle.
+
+## Support
 
-- See `packages/dot/docs/` in the [`@arki/dot`](https://www.npmjs.com/package/@arki/dot)
-  package for plugin authoring, lifecycle, diagnostics, and the
-  [adapter authoring guide](https://github.com/arkijs/arki/blob/main/packages/dot/docs/adapter-authoring.md).
+Report bugs at [github.com/arki-labs/arki/issues](https://github.com/arki-labs/arki/issues).
 
 <!-- bench:start -->
+
 ## Benchmarks
 
 Defining and validating a 15-variable server environment with `defineEnv()`, against `@t3-oss/env-core` (which it wraps), envalid, and a plain zod object parse.
@@ -85,39 +254,39 @@ Node v22.13.1 on Apple M2 Max, 2026-10-13. Median time per operation, lower is b
 
 Each call builds a fresh environment from scratch, validates every variable, then reads `PORT`.
 
-| Library | Time / op | vs fastest |
-| --- | ---: | ---: |
-| @arki/env defineEnv() | 25.03 µs | fastest |
-| @t3-oss/env-core createEnv() (used directly) | 306.02 µs | 12.22× |
-| envalid cleanEnv() | 59.23 µs | 2.37× |
-| zod z.object().parse(process.env) | 177.92 µs | 7.11× |
+| Library                                      | Time / op | vs fastest |
+| -------------------------------------------- | --------: | ---------: |
+| @arki/env defineEnv()                        |  25.03 µs |    fastest |
+| @t3-oss/env-core createEnv() (used directly) | 306.02 µs |     12.22× |
+| envalid cleanEnv()                           |  59.23 µs |      2.37× |
+| zod z.object().parse(process.env)            | 177.92 µs |      7.11× |
 
 ### Define only (no read)
 
 Declare the environment and never read it. `defineEnv()` defers all work to the first read; the others validate immediately.
 
-| Library | Time / op | vs fastest |
-| --- | ---: | ---: |
-| @arki/env defineEnv() (lazy, no validation yet) | 126.8 ns | fastest |
-| @t3-oss/env-core createEnv() (validates now) | 519.07 µs | 4094.95× |
-| envalid cleanEnv() (validates now) | 115.66 µs | 912.46× |
-| zod z.object().parse(process.env) (validates now) | 431.26 µs | 3402.26× |
+| Library                                           | Time / op | vs fastest |
+| ------------------------------------------------- | --------: | ---------: |
+| @arki/env defineEnv() (lazy, no validation yet)   |  126.8 ns |    fastest |
+| @t3-oss/env-core createEnv() (validates now)      | 519.07 µs |   4094.95× |
+| envalid cleanEnv() (validates now)                | 115.66 µs |    912.46× |
+| zod z.object().parse(process.env) (validates now) | 431.26 µs |   3402.26× |
 
 ### Read one value from an already-validated environment
 
 The hot path: `env.PORT` after the environment exists.
 
-| Library | Time / op | vs fastest |
-| --- | ---: | ---: |
-| @arki/env (lazy object over createEnv) | 229.1 ns | 28.25× |
-| @t3-oss/env-core createEnv() | 50.3 ns | 6.20× |
-| envalid cleanEnv() | 83.8 ns | 10.34× |
-| zod parsed plain object | 8.1 ns | fastest |
+| Library                                | Time / op | vs fastest |
+| -------------------------------------- | --------: | ---------: |
+| @arki/env (lazy object over createEnv) |  229.1 ns |     28.25× |
+| @t3-oss/env-core createEnv()           |   50.3 ns |      6.20× |
+| envalid cleanEnv()                     |   83.8 ns |     10.34× |
+| zod parsed plain object                |    8.1 ns |    fastest |
 
-Read the rows with the contracts in mind:
+Read the rows with the presets in mind:
 
 - `defineEnv()` is lazy: it builds and validates the environment on the first property read, so "define + first read" is the fair row for it. The "define only" group shows what declaring an env costs before anything reads it.
-- Validation is forced on (`skipValidation: false`) for `defineEnv()` and `createEnv`, because `defineEnv()` skips validation outside development by default.
+- Validation is forced on (`skipValidation: false`) for `defineEnv()` and `createEnv`, so the numbers do not depend on `SKIP_ENV_VALIDATION`.
 - `defineEnv()` and `createEnv` share the same zod schemas, so the gap between them is the wrapper alone: building `runtimeEnv` from `process.env`, a labelled error handler, and the lazy object. envalid uses its own validators, and the plain zod parse does no env-specific work (no empty-string handling, no frozen result).
 - `createEnv`, envalid and the zod parse are given the whole `process.env`, as their docs show, so their cost grows with how many variables the process has. `defineEnv()` reads only the keys it declares. The gap therefore depends on the size of the environment it runs in.
 
@@ -126,4 +295,4 @@ Reproduce with `bun run bench` in the package directory; regenerate this section
 
 ## License
 
-MIT — see [LICENSE](./LICENSE).
+MIT. See [LICENSE](./LICENSE).