@venizia/ignis-docs 0.2.1-0 → 0.2.1-1

package/content/references/base/secrets.md

@@ -6,12 +6,12 @@ difficulty: advanced
 
 # Deep Dive: Secrets & Vault
 
-Technical reference for the `Secrets` provider family - how IGNIS loads configuration and credentials from a vault instead of reading `process.env` directly, hydrates static secrets at boot, and rotates dynamic database credentials into a live connection pool without a restart.
+Technical reference for the `Secrets` provider family. It covers how IGNIS loads configuration and credentials from a vault instead of reading `process.env` directly, hydrates static secrets at boot, and rotates dynamic database credentials into a live connection pool without a restart.
 
 > [!IMPORTANT] Dormant by default
 > An application that does not override `registerSecrets()` gets the `system-envs` provider, which reads `process.env` exactly as before. The whole subsystem is additive - existing apps behave identically until they opt in.
 
-**Files:** `packages/helpers/src/modules/secrets/*.ts` (provider family) and `packages/core/src/base/applications/base.ts` (`hydrateSecrets()` lifecycle, DI binding, rotation wiring)
+**Files:** `packages/helpers/src/modules/secrets/*.ts` (provider family) and `packages/core-server/src/base/applications/base.ts` (`hydrateSecrets()` lifecycle, DI binding, rotation wiring)
 
 ## Quick Reference
 
@@ -45,7 +45,7 @@ AbstractSecretsHelper (BaseHelper; TTL cache, lease registry, renewal scheduler,
   └── DotenvVaultHelper      // 'dotenv-vault'    - encrypted .env.vault, static only.
 ```
 
-The renewal scheduler, TTL cache, lease registry, and `onRotate` dispatch all live in `AbstractSecretsHelper`. A concrete provider implements only the raw calls against its backend (`fetchRaw`, `renewRaw`, `revokeRaw`), which is why the two static providers are thin and why only HashiCorp exercises the lease machinery.
+The renewal scheduler, TTL cache, lease registry, and `onRotate` dispatch all live in `AbstractSecretsHelper`. A concrete provider implements only the raw calls against its backend (`fetchRaw`, `renewRaw`, `revokeRaw`). That's why the two static providers are thin, and why only HashiCorp exercises the lease machinery.
 
 ## `ISecretsHelper` Interface
 
@@ -92,7 +92,7 @@ interface ISecretRotatable {
 ```
 
 > [!NOTE] Static vs dynamic secrets
-> `get()` / `getBundle()` return static values (KV, env) and are TTL-cached. `lease()` returns a dynamic, lease-bearing secret and is supported only by `HashiCorpVaultHelper`; the static providers throw an explicit NotSupported error rather than returning a fake lease.
+> `get()` / `getBundle()` return static values (KV, env) and are TTL-cached. `lease()` returns a dynamic, lease-bearing secret and is supported only by `HashiCorpVaultHelper`. The static providers throw an explicit NotSupported error instead of returning a fake lease.
 
 ## Registration
 
@@ -121,7 +121,7 @@ interface ISecretsRegistration {
 ### `registerSecrets()` default
 
 ```typescript
-// packages/core/src/base/applications/base.ts
+// packages/core-server/src/base/applications/base.ts
 registerSecrets(): ValueOrPromise<ISecretsRegistration> {
   return { provider: SecretProviders.SYSTEM_ENVS };
 }
@@ -176,7 +176,7 @@ validateEnvs → staticConfigure → preConfigure
 3. Binds the live provider at `CoreBindings.APPLICATION_CONFIG` (`@app/config`) as a singleton.
 4. Registers a post-stop hook (`secrets.shutdown`) so `provider.shutdown()` runs on teardown, revoking outstanding leases.
 
-`wireSecretRotatables()` runs after datasources are registered: for each `lease` entry it resolves the datasource at `entry.key` and, if the instance implements `onSecretRotated`, calls `provider.registerRotatable({ key, target })`. A datasource that does not implement the hook is skipped.
+`wireSecretRotatables()` runs after datasources are registered. For each `lease` entry it resolves the datasource at `entry.key` and, if the instance implements `onSecretRotated`, calls `provider.registerRotatable({ key, target })`. A datasource that does not implement the hook is skipped.
 
 > [!TIP] Why a lifecycle phase and not a Component
 > Components register *after* datasources, but secrets must be resolved *before* datasources build their pools. Hydration is therefore a dedicated phase, not a component.
@@ -190,15 +190,16 @@ validateEnvs → staticConfigure → preConfigure
 | Development set | Log a warning, fall back to a `system-envs` provider, continue booting |
 | Everything else (prod, staging, and any unrecognized name) | Throw `ApplicationError`, crash the boot |
 
-The fallback in development builds a fresh `SystemEnvsHelper` and shuts down the partially-built provider first, so a half-authenticated Vault client leaves no renewal timer or lease behind.
+The fallback in development builds a fresh `SystemEnvsHelper`. It shuts down the partially-built provider first, so a half-authenticated Vault client leaves no renewal timer or lease behind.
 
 ## `AbstractSecretsHelper` Machinery
 
 **File:** `packages/helpers/src/modules/secrets/base/abstract.helper.ts`
 
 - **TTL cache** - `get()` / `getBundle()` cache each path for `cacheTtlSeconds` (default 300) and re-fetch on expiry.
-- **Renewal scheduler** - each lease schedules a renewal at `ttlSeconds × renewBeforeRatio` (default 0.66) through an injectable timer seam. On fire, `renewRaw()` extends the same lease; on renew failure or max-TTL, `fetchRaw()` mints a fresh lease and a single rotation is dispatched.
-- **Rotation dispatch** - `onRotate` handlers run first, then the registered rotatables for that key run **in series**; a throwing consumer is logged and does not abort the others.
+- **Renewal scheduler** - each lease schedules a renewal at `ttlSeconds × renewBeforeRatio` (default 0.66) through an injectable timer seam.
+- **On renewal fire** - `renewRaw()` extends the same lease. On renew failure or max-TTL, `fetchRaw()` mints a fresh lease and a single rotation is dispatched instead.
+- **Rotation dispatch** - `onRotate` handlers run first. The registered rotatables for that key then run **in series**; a throwing consumer is logged and does not abort the others.
 - **Shutdown** - clears every timer and revokes every lease via `revokeRaw()`.
 
 The scheduler, cache, and clock are injectable, so the machinery is tested deterministically without real timers or a live vault.
@@ -207,12 +208,15 @@ The scheduler, cache, and clock are injectable, so the machinery is tested deter
 
 **File:** `packages/helpers/src/modules/secrets/hashicorp/hashicorp.helper.ts`
 
-- **Auth** - a Zod discriminated union on `method`: `token`, `app-role` (`roleId` + `secretId`), `kubernetes` (`role`, optional `jwtPath`). `configure()` logs in and stores the Vault token.
+- **Auth** - a Zod discriminated union on `method`: `token` (`token`), `app-role` (`roleId` + `secretId`, optional `mountPath`), `kubernetes` (`role`, optional `jwtPath` and `mountPath`). `configure()` logs in and stores the Vault token. `mountPath` defaults to the method name - `approle` and `kubernetes`.
 - **KV v2** - `getBundle()` unwraps the KV-v2 `.data.data` envelope automatically.
 - **Dynamic secrets** - a read against a dynamic engine (for example `database/creds/...`) returns a lease (`lease_id`, `lease_duration`, `renewable`), which drives the renewal scheduler.
-- **Token self-renewal** - the Vault auth token has its own TTL. The provider schedules the token for renewal in the same cadence and re-runs the login flow (re-auth) if the token can no longer be renewed, so AppRole / Kubernetes deployments survive past the token TTL without a restart.
+- **Token self-renewal** - the Vault auth token has its own TTL. The provider schedules the token for renewal in the same cadence as leases.
+- **Re-auth on expiry** - if the token can no longer be renewed, the provider re-runs the login flow, so AppRole / Kubernetes deployments survive past the token TTL without a restart.
 
-`node-vault` is an optional peer. It is reached only through the `@venizia/ignis-helpers/hashicorp-vault` sub-path and a bundler-invisible dynamic import (`importOptionalModule`), so importing the root package never requires it - and `Bun.build`-compiled applications need no `external: ['node-vault']` workaround. An application that does use this provider and compiles a binary must ship `node-vault` in `node_modules` next to the binary, or inject a ready-made `client` through the helper options.
+`node-vault` is an optional peer. It is reached only through the `@venizia/ignis-helpers/hashicorp-vault` sub-path and a bundler-invisible dynamic import (`ModuleUtility.load`), so importing the root package never requires it. `Bun.build`-compiled applications need no `external: ['node-vault']` workaround.
+
+An application that does use this provider and compiles a binary must ship `node-vault` in `node_modules` next to the binary. Alternatively, inject a ready-made `client` through the helper options, or import `node-vault` statically and hand it over with `ModuleUtility.register({ modules: { 'node-vault': nodeVault } })` at startup.
 
 ## Dotenv Vault Provider
 
@@ -229,7 +233,7 @@ The PostgreSQL datasource implements `onSecretRotated()` on `AbstractRelationalD
 1. Capture the current pool.
 2. Apply the new credentials onto `this.settings` (`{ username, password }` maps to pg's `{ user, password }`).
 3. Clear the driver / connector / client, re-run `configure()` to build a fresh pool, and re-wire the driver.
-4. Drain the old pool with `end()` - which resolves once checked-out clients are released, so in-flight transactions finish on the old pool while new work uses the new one.
+4. Drain the old pool with `end()`. It resolves once checked-out clients are released, so in-flight transactions finish on the old pool while new work uses the new one.
 
 > [!WARNING] configure() must read from this.settings
 > Rotation applies new credentials by writing them onto `this.settings` and re-running `configure()`. A `configure()` that builds its pool from a hard-coded connection string, or reads `Envs` directly, will rebuild with **stale** credentials.

package/content/references/base/services.md

@@ -8,7 +8,7 @@ difficulty: beginner
 
 Technical reference for `BaseService` - the foundation for the business logic layer in IGNIS.
 
-**File:** `packages/core/src/base/services/base.ts`
+**File:** `packages/core-server/src/base/services/base.ts`
 
 ## Quick Reference
 
@@ -29,7 +29,7 @@ Technical reference for `BaseService` - the foundation for the business logic la
 Abstract class that all application services must extend.
 
 ```typescript
-// packages/core/src/base/services/base.ts
+// packages/core-server/src/base/services/base.ts
 import { BaseHelper } from '@venizia/ignis-helpers';
 import { IService } from './types';
 
@@ -65,7 +65,7 @@ this.service(GreeterService);         // binds as 'services.GreeterService'
 `this.service(Ctor)` is implemented directly on `BaseApplication`:
 
 ```typescript
-// packages/core/src/base/applications/base.ts
+// packages/core-server/src/base/applications/base.ts
 service<Base extends IService, Args extends AnyObject = any>(
   ctor: TClass<Base>,
   opts?: TMixinOpts<Args>,
@@ -244,7 +244,9 @@ this.service(OrderService);
 
 ### Abstract Base Services
 
-For shared dependencies across multiple related services, define an abstract base. The container only ever `instantiate()`s the **concrete** class (`this.service(UserAuditTestService)` registers `UserAuditTestService`, never `BaseTestService`), and the hard DI rule - every constructor parameter of a container-instantiated class must carry `@inject` - applies to that concrete constructor. A `scope: string` computed from `ClassName.name` is not something the container can supply anyway, so it cannot sit as a bare constructor parameter next to an `@inject`-decorated one. The shared repository is injected as a **property** on the base instead, and the concrete subclass's constructor is left with zero parameters - nothing to decorate, nothing to violate:
+For shared dependencies across multiple related services, define an abstract base. The container only ever `instantiate()`s the **concrete** class - `this.service(UserAuditTestService)` registers `UserAuditTestService`, never `BaseTestService`. The hard DI rule - every constructor parameter of a container-instantiated class must carry `@inject` - applies to that concrete constructor.
+
+A `scope: string` computed from `ClassName.name` is not something the container can supply. So it cannot sit as a bare constructor parameter next to an `@inject`-decorated one. The shared repository is injected as a **property** on the base instead. The concrete subclass's constructor is left with zero parameters - nothing to decorate, nothing to violate:
 
 ```typescript
 // Shared repository access for a group of test services - property injection,

package/content/references/configuration/environment-variables.md

@@ -4,10 +4,10 @@ Complete reference of all environment variables used by the IGNIS framework, gro
 
 **Files:**
 
-- [`packages/core/src/common/environments.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/common/environments.ts) - `EnvironmentKeys`
+- [`packages/core-server/src/common/environments.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/common/environments.ts) - `EnvironmentKeys`
 - [`packages/helpers/src/modules/env/app-env.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/env/app-env.ts) - `applicationEnvironment`, `Environment`
-- [`packages/core/src/base/applications/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/applications/abstract.ts) - `validateEnvs()`, host/port resolution priority
-- [`packages/core/src/base/applications/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/applications/base.ts) - `registerSecrets()`, `hydrateSecrets()`
+- [`packages/core-server/src/base/applications/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/applications/abstract.ts) - `validateEnvs()`, host/port resolution priority
+- [`packages/core-server/src/base/applications/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/applications/base.ts) - `registerSecrets()`, `hydrateSecrets()`
 - [`packages/helpers/src/modules/secrets/common/constants.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/secrets/common/constants.ts) - `SecretProviders`, `VaultAuthMethods`
 - [`packages/helpers/src/modules/secrets/hashicorp/hashicorp.helper.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/secrets/hashicorp/hashicorp.helper.ts) - HashiCorp Vault helper
 
@@ -43,38 +43,38 @@ Create a `.env` file in your project root:
 ```bash
 # .env
 
-# =====================
+# ----------------------
 # APPLICATION
-# =====================
+# ----------------------
 APP_ENV_APPLICATION_NAME=my-app
 APP_ENV_APPLICATION_TIMEZONE=UTC
 
-# =====================
+# ----------------------
 # SERVER
-# =====================
+# ----------------------
 APP_ENV_SERVER_HOST=0.0.0.0
 APP_ENV_SERVER_PORT=3000
 APP_ENV_SERVER_BASE_PATH=/api
 
-# =====================
+# ----------------------
 # DATABASE (PostgreSQL)
-# =====================
+# ----------------------
 APP_ENV_POSTGRES_HOST=localhost
 APP_ENV_POSTGRES_PORT=5432
 APP_ENV_POSTGRES_USERNAME=postgres
 APP_ENV_POSTGRES_PASSWORD=your_password_here
 APP_ENV_POSTGRES_DATABASE=my_database
 
-# =====================
+# ----------------------
 # AUTHENTICATION
-# =====================
+# ----------------------
 APP_ENV_APPLICATION_SECRET=generate-a-strong-random-secret
 APP_ENV_JWT_SECRET=generate-another-strong-random-secret
 APP_ENV_JWT_EXPIRES_IN=86400
 
-# =====================
+# ----------------------
 # LOGGING
-# =====================
+# ----------------------
 APP_ENV_LOGGER_FOLDER_PATH=./logs
 ```
 
@@ -124,7 +124,7 @@ APP_ENV_SERVER_BASE_PATH=/v1/api
 
 ### Priority Order
 
-The server host/port resolution uses this priority (`packages/core/src/base/applications/abstract.ts`):
+The server host/port resolution uses this priority (`packages/core-server/src/base/applications/abstract.ts`):
 1. Explicit config passed to the application constructor
 2. `HOST`/`PORT` variables (for cloud platforms)
 3. `APP_ENV_SERVER_HOST`/`APP_ENV_SERVER_PORT` variables
@@ -199,7 +199,7 @@ export class PostgresDataSource extends BaseDataSource {
 
 - **Not read directly.** The `AuthenticateComponent` receives its secrets programmatically via the `jwtOptions` binding (`jwtSecret`, `getTokenExpiresFn`) - it never reads these environment variables itself.
 - **`EnvironmentKeys` is the convention, not a requirement.** These constants are the conventional way for your application to supply those values into the binding.
-- **A missing or placeholder secret fails the boot.** The component throws at startup if `jwtSecret` is missing or left at the placeholder value - wiring it from an unset environment variable fails the same way.
+- **A missing or placeholder secret fails the boot.** The component throws at startup if `jwtSecret` is missing or left at the placeholder value. Wiring it from an unset environment variable fails the same way.
 
 ### Generate Strong Secrets
 
@@ -236,6 +236,7 @@ APP_ENV_JWT_EXPIRES_IN=86400
 | `APP_ENV_LOGGER_LEVEL` | No | `debug` | Logger-level floor; transports without their own level inherit it |
 | `APP_ENV_LOGGER_INSPECT_DEPTH` | No | `5` | How deep a `%s` argument is inspected. Node hard-codes depth `0` for `%s`, which prints `[Object]` one level in; IGNIS widens it. Non-negative integers only - an absent, invalid or negative value falls back to `5` |
 | `APP_ENV_LOGGER_DO_REDACT` | No | `true` | Secret redaction in logged values. ONLY the literal `false` disables it (reveals raw credentials in log lines); anything else keeps redaction ON. Never disable in production |
+| `APP_ENV_LOGGER_COLOR` | No | _(unset)_ | ANSI color on console log lines. Unset means auto: ON in a development `NODE_ENV`, OFF in `production`, `staging`, `uat` and any unrecognized name. `NO_COLOR` also turns it off |
 | `APP_ENV_LOGGER_FILE_FREQUENCY` | No | `1h` | Log file rotation frequency |
 | `APP_ENV_LOGGER_FILE_MAX_SIZE` | No | `100m` | Max size per log file |
 | `APP_ENV_LOGGER_FILE_MAX_FILES` | No | `5d` | Log file retention |
@@ -328,9 +329,14 @@ APP_ENV_MAIL_REFRESH_TOKEN=your-oauth2-refresh-token
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `APP_ENV_APPLICATION_DS_MIGRATION` | No | - | DataSource name for migrations |
-| `APP_ENV_APPLICATION_DS_AUTHORIZE` | No | - | DataSource name for auth |
-| `APP_ENV_APPLICATION_DS_OAUTH2` | No | - | DataSource name for OAuth2 |
+| `APP_ENV_DS_MIGRATION` | No | `postgres` | DataSource name for migrations. Read at boot and printed in the startup banner |
+| `APP_ENV_DS_AUTHORIZE` | No | `postgres` | DataSource name for authorization. Read at boot and printed in the startup banner |
+| `APP_ENV_AUTO_PROVISION_COLLECTION` | No | `false` | Lets a search datasource create a missing collection on first use. `true` or `1` enables it; the `autoProvision` constructor option overrides it |
+
+> [!WARNING] These two name the datasource, they do not select it
+> `APP_ENV_DS_MIGRATION` and `APP_ENV_DS_AUTHORIZE` reach the startup banner and nothing else - the framework does not resolve a datasource from either. Wire your own lookup if you need one.
+
+`Environments` (`packages/core-server/src/common/environments.ts`) also declares `APP_ENV_APPLICATION_DS_MIGRATION`, `APP_ENV_APPLICATION_DS_AUTHORIZE` and `APP_ENV_APPLICATION_DS_OAUTH2`. Those are name constants with no reader anywhere in the framework - setting them changes nothing.
 
 
 ## Debug Variables
@@ -340,6 +346,7 @@ APP_ENV_MAIL_REFRESH_TOKEN=your-oauth2-refresh-token
 | `DEBUG` | No | - | Enable debug mode |
 | `NODE_ENV` | No | `development` | Environment mode. One of `local`, `debug`, `development`, `dev`, `sit`, `uat`, `alpha`, `beta`, `staging`, `production` |
 | `ALLOW_EMPTY_ENV_VALUE` | No | `false` | Allow empty env values |
+| `RUN_MODE` | No | - | Printed in the startup banner. The framework never branches on it - read it yourself to split a migrate run from a serve run |
 
 - **Fail-closed by default.** An environment IGNIS does not recognize is treated as production, so error responses are sanitized.
 - **Development environments expose error detail.** `local`, `debug`, `development`, `dev`, and `sit` are the development set - only these show internal error detail.
@@ -359,7 +366,8 @@ NODE_ENV=production
 
 ## Secrets & Vault
 
-- **A `.env` file is one option, not a requirement.** IGNIS can load these variables from a vault (HashiCorp Vault, an encrypted `.env.vault`, or plain `process.env`) and **hydrate** them into the same `APP_ENV_*` keys at boot. Code that reads `process.env.APP_ENV_*` keeps working unchanged - the values simply arrive from the vault instead of a file.
+- **A `.env` file is one option, not a requirement.** IGNIS can load these variables from a vault (HashiCorp Vault, an encrypted `.env.vault`, or plain `process.env`). It **hydrates** them into the same `APP_ENV_*` keys at boot.
+- **Hydration is transparent to your code.** Code that reads `process.env.APP_ENV_*` keeps working unchanged - the values arrive from the vault instead of a file.
 - **Hydration runs before datasources are configured** (after `preConfigure()`, before `registerDataSources()`), so a hydrated `APP_ENV_DS_PASSWORD` is available exactly where a file-based one would be.
 - **Vault values take precedence over `process.env`** when the provider is live - a hydrated key overwrites whatever was already in `process.env`.
 
@@ -375,7 +383,7 @@ override registerSecrets() {
 ```
 
 > [!NOTE] Failure policy
-> If the vault is unreachable, development environments (`local`, `debug`, `development`, `dev`, `sit`) fall back to `process.env`; every other environment fails the boot rather than starting with missing secrets.
+> If the vault is unreachable, development environments (`local`, `debug`, `development`, `dev`, `sit`) fall back to `process.env`. Every other environment fails the boot rather than starting with missing secrets.
 
 See the [Secrets & Vault guide](/guides/core-concepts/secrets-vault) for setup and the [Secrets & Vault reference](/references/base/secrets) for the full API.
 
@@ -414,7 +422,7 @@ MY_APP_POSTGRES_HOST=localhost
 
 ## Validation
 
-On startup, IGNIS iterates every `APP_ENV_*` (prefixed) variable that is set and throws if any has an empty value (`validateEnvs` in `packages/core/src/base/applications/abstract.ts`). It does not check for variables that are absent entirely - component-level validation (e.g., the authentication component's `jwtSecret` check) covers required values.
+On startup, IGNIS iterates every `APP_ENV_*` (prefixed) variable that is set and throws if any has an empty value (`validateEnvs` in `packages/core-server/src/base/applications/abstract.ts`). It does not check for variables that are absent entirely - component-level validation (e.g., the authentication component's `jwtSecret` check) covers required values.
 
 ### Disable Validation
 
@@ -436,9 +444,9 @@ ALLOW_EMPTY_ENV_VALUE=true
 ## Complete .env.example
 
 ```bash
-# ===========================================
+# ----------------------
 # IGNIS ENVIRONMENT VARIABLES
-# ===========================================
+# ----------------------
 # Copy this file to .env and fill in values
 
 # APPLICATION

package/content/references/configuration/index.md

@@ -52,8 +52,10 @@ const host = applicationEnvironment.get<string>(EnvironmentKeys.APP_ENV_POSTGRES
 ## How it works
 
 - **One prefix, layered files.** Everything IGNIS reads is prefixed `APP_ENV_` (configurable - see the [Environment Variables Reference](./environment-variables.md#custom-environment-prefix)). Layer `.env`, `.env.local`, and `.env.{NODE_ENV}` the same way any dotenv-based tool does.
-- **`applicationEnvironment` snapshots `process.env` once at import.** It's built from whatever is in `process.env` when `@venizia/ignis-helpers` loads - values arriving after that (e.g., set programmatically at runtime) won't appear in `.keys()` unless merged in explicitly (secret hydration does this - see below).
-- **Startup validation is fail-closed on emptiness, not absence.** IGNIS iterates every `APP_ENV_*` key that IS set and throws if its value is empty; it does not require a variable to exist at all. Bypass with `ALLOW_EMPTY_ENV_VALUE=true`. Component-level checks (e.g., the authentication component's `jwtSecret` check) cover values that must be present.
+- **`applicationEnvironment` snapshots `process.env` once at import.** It's built from whatever is in `process.env` when `@venizia/ignis-helpers` loads.
+- **Late values need an explicit merge.** A value set programmatically at runtime, after that snapshot, won't appear in `.keys()` unless merged in - secret hydration does this, see below.
+- **Startup validation is fail-closed on emptiness, not absence.** IGNIS iterates every `APP_ENV_*` key that IS set and throws if its value is empty. It does not require a variable to exist at all.
+- **Bypass and per-component checks.** Bypass emptiness validation with `ALLOW_EMPTY_ENV_VALUE=true`. Component-level checks (e.g., the authentication component's `jwtSecret` check) still cover values that must be present.
 - **Secrets don't have to live in a file.** IGNIS can hydrate `APP_ENV_*` keys from a vault at boot, before datasources are configured - see [Secrets & Vault](./environment-variables.md#secrets-vault).
 
 ## Common tasks
@@ -125,6 +127,6 @@ import { EnvironmentKeys } from '@venizia/ignis';
 
 **Files:**
 
-- [`packages/core/src/common/environments.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/common/environments.ts) - `EnvironmentKeys`
+- [`packages/core-server/src/common/environments.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/common/environments.ts) - `EnvironmentKeys`
 - [`packages/helpers/src/modules/env/app-env.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/env/app-env.ts) - `applicationEnvironment`, `Environment`, `ApplicationEnvironment`
-- [`packages/core/src/base/applications/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/applications/abstract.ts) - `validateEnvs()`, host/port resolution
+- [`packages/core-server/src/base/applications/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/applications/abstract.ts) - `validateEnvs()`, host/port resolution

package/content/references/index.md

@@ -162,7 +162,7 @@ import {
 import {
   LoggerFactory,
   RedisSingleHelper,
-  QueueHelper,
+  SequentialQueueHelper,
 } from '@venizia/ignis-helpers';
 
 // DI Container

package/content/references/utilities/duration.md

@@ -0,0 +1,85 @@
+---
+title: Duration Utility
+description: A unit vocabulary, written-duration parsing, and conversion between units and milliseconds
+difficulty: beginner
+lastUpdated: 2026-08-15
+---
+
+# Duration Utility
+
+A duration is `{ unit, value }`. This turns that into milliseconds, reads it out of a written string like `30d`, and converts between units.
+
+## In one example
+
+```typescript
+import { DurationMultipliers, DurationUnits } from '@venizia/ignis-helpers/common';
+
+const gracePeriod = { unit: DurationUnits.DAY, value: 30 };
+
+DurationMultipliers.toMilliseconds(gracePeriod); // 2_592_000_000
+DurationMultipliers.parseToMilliseconds('30d'); // 2_592_000_000
+DurationMultipliers.convert({ value: 36, from: 'hour', to: 'day' }); // 1.5
+```
+
+Everything here is browser-pure, so it works unchanged in a Worker. Import from `@venizia/ignis-helpers/common`, or from the root barrel if you already depend on it.
+
+## Units
+
+| Constant | Value | Milliseconds |
+|---|---|---|
+| `DurationUnits.MILLISECOND` | `'millisecond'` | 1 |
+| `DurationUnits.SECOND` | `'second'` | 1 000 |
+| `DurationUnits.MINUTE` | `'minute'` | 60 000 |
+| `DurationUnits.HOUR` | `'hour'` | 3 600 000 |
+| `DurationUnits.DAY` | `'day'` | 86 400 000 |
+| `DurationUnits.WEEK` | `'week'` | 604 800 000 |
+| `DurationUnits.MONTH` | `'month'` | 2 592 000 000 |
+| `DurationUnits.YEAR` | `'year'` | 31 536 000 000 |
+
+`TDurationUnit` is the union of those eight values. `IDuration` is `{ unit: TDurationUnit; value: number }`.
+
+## Functions
+
+| Function | Signature | What it does |
+|---|---|---|
+| `DurationUnits.isValid` | `isValid(input: string): input is TDurationUnit` | `true` when `input` is one of the eight canonical names. |
+| `DurationAliases.resolve` | `resolve(input: string): TDurationUnit \| null` | Reads a written unit - `'d'`, `'days'`, `'DAY'` - into its canonical name. |
+| `DurationMultipliers.toMilliseconds` | `toMilliseconds(opts: IDuration \| null): number \| null` | Converts a duration to milliseconds, rounded. |
+| `DurationMultipliers.fromMilliseconds` | `fromMilliseconds(opts: { milliseconds: number; unit: TDurationUnit }): number \| null` | The inverse. Fractional, not rounded. |
+| `DurationMultipliers.convert` | `convert(opts: { value: number; from: TDurationUnit; to: TDurationUnit }): number \| null` | Converts between two units. Fractional. |
+| `DurationMultipliers.parse` | `parse(input: string): IDuration \| null` | Reads `'30d'`, `'1500 ms'`, `'2 hours'` into an `IDuration`. |
+| `DurationMultipliers.parseToMilliseconds` | `parseToMilliseconds(input: string): number \| null` | `parse` followed by `toMilliseconds`. |
+
+## A month is 30 days and a year is 365
+
+These size a **window** - a grace period, a cache TTL, a near-expiry horizon. They are not calendar arithmetic.
+
+Adding `MONTH` to 31 January lands on 2 March in a leap year and 3 March otherwise. If you need a real calendar date, use [the date utility](./date.md) and let `dayjs` handle months.
+
+## Every function answers `null`, never throws
+
+An unknown unit, a `NaN` value, an unreadable string - all return `null`. A caller that wants an error raises its own, with its own context:
+
+```typescript
+const ttlMs = DurationMultipliers.parseToMilliseconds(config.cacheTtl);
+
+if (ttlMs === null) {
+  throw getError({ message: `[cache] Unreadable TTL: '${config.cacheTtl}'` });
+}
+```
+
+Zero is a real duration, not an absent one - `{ unit: 'day', value: 0 }` converts to `0`. A negative value converts too, so a caller deciding what a negative window means keeps that decision.
+
+## Writing a duration
+
+`parse` accepts one number, an optional space, and one unit: `30d`, `1.5h`, `-2 Hours`, `1500 ms`. Anything it cannot read whole is `null` - there is no partial credit, so `'30d extra'` fails rather than silently meaning 30 days.
+
+Accepted spellings are the member names of `DurationAliases`, lower-cased: short (`d`), abbreviated (`wk`), singular (`day`) and plural (`days`).
+
+**`m` is minute and `mo` is month.** That is the choice every duration library makes, and the one ambiguity worth checking before you write a config value. There is no single-letter month.
+
+## Notes
+
+- **The fast path allocates nothing.** `resolve` tries your input as given before normalising it, so a canonical `'day'` costs about 2ns while a messy `'  Days '` pays the ~80ns that trimming and upper-casing costs. Pass canonical spellings in a loop.
+- **`toMilliseconds` rounds; `fromMilliseconds` and `convert` do not.** Rounding on the way out would silently lose a 36-hour window asked for in days.
+- **The alias table is derived from `DurationAliases`**, not hand-listed beside it, so a new spelling is one member and the two cannot drift.

package/content/references/utilities/index.md

@@ -8,12 +8,14 @@ Pure, standalone functions providing common, reusable logic for the IGNIS framew
 |---------|---------|---------|---------------|
 | **Crypto** | `ignis-helpers` | Cryptographic hashing | `hash()` |
 | **Date** | `ignis-helpers` | Date/time manipulation | `dayjs`, `sleep()`, `isWeekday()`, `getDateTz()`, `hrTime()` |
+| **Duration** | `ignis-helpers` | Duration units and conversion | `DurationUnits`, `DurationMultipliers.toMilliseconds()`, `.parseToMilliseconds()` |
 | **JSX** | `ignis` | HTML/JSX responses | `htmlContent()`, `htmlResponse()` |
-| **Module** | `ignis-helpers` | Module validation | `validateModule()` |
+| **Module** | `ignis-helpers` | Optional peer loading | `ModuleUtility` |
 | **Parse** | `ignis-helpers` | Data type conversion | `int()`, `float()`, `toBoolean()`, `toCamel()` |
 | **Performance** | `ignis-helpers` | Execution timing | `executeWithPerformanceMeasure()`, `getPerformanceCheckpoint()` |
 | **Promise** | `ignis-helpers` | Promise helpers | `executePromiseWithLimit()`, `isPromiseLike()`, `getDeepProperty()` |
 | **Request** | `ignis-helpers` | HTTP utilities | `parseMultipartBody()`, `sanitizeFilename()`, `createContentDispositionHeader()` |
+| **Retry** | `ignis-helpers` | Backoff-driven retries | `executeWithRetry()`, `executeWithRetryUntil()`, `computeBackoffDelayMs()` |
 | **Schema** | `ignis` | Zod schema helpers | `jsonContent()`, `jsonResponse()`, `requiredString()`, `idParamsSchema()` |
 | **Statuses** | `ignis` | Status code constants | `Statuses`, `CommonStatuses`, `UserStatuses`, `RoleStatuses` |
 
@@ -29,6 +31,7 @@ Pure, standalone functions providing common, reusable logic for the IGNIS framew
 ### Time & Performance
 
 - [**Date**](./date.md) - Date and time manipulation functions built on `dayjs` with timezone support
+- [**Duration**](./duration.md) - A unit vocabulary, written-duration parsing, and conversion between units and milliseconds
 - [**Performance**](./performance.md) - Utilities for measuring code execution time and performance profiling
 
 ### Async & HTTP
@@ -36,6 +39,7 @@ Pure, standalone functions providing common, reusable logic for the IGNIS framew
 - [**JSX**](./jsx.md) - HTML and JSX response utilities for server-side rendering and OpenAPI documentation
 - [**Promise**](./promise.md) - Helper functions for working with Promises including concurrency limiting and value transformation
 - [**Request**](./request.md) - HTTP request utilities for parsing multipart form data and creating secure Content-Disposition headers
+- [**Retry**](./retry.md) - Backoff-driven retry helpers - error-triggered (`executeWithRetry`) and predicate-driven (`executeWithRetryUntil`)
 
 ### Runtime
 

package/content/references/utilities/jsx-reference.md

@@ -10,16 +10,16 @@ Exhaustive reference for `htmlContent()`, `htmlResponse()`, and `BaseRestControl
 
 **Files:**
 
-- [`packages/core/src/utilities/jsx.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/utilities/jsx.utility.ts) - `htmlContent`, `htmlResponse`
-- [`packages/core/src/base/controllers/rest/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/controllers/rest/base.ts) - `BaseRestController.defineJSXRoute`
-- [`packages/core/src/base/controllers/rest/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/controllers/rest/abstract.ts) - `AbstractRestController.getJSXRouteConfigs`
+- [`packages/core-server/src/utilities/jsx.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/utilities/jsx.utility.ts) - `htmlContent`, `htmlResponse`
+- [`packages/core-server/src/base/controllers/rest/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/controllers/rest/base.ts) - `BaseRestController.defineJSXRoute`
+- [`packages/core-server/src/base/controllers/rest/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/controllers/rest/abstract.ts) - `AbstractRestController.getJSXRouteConfigs`
 - [`packages/helpers/src/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/common/types.ts) - `FC`, `PropsWithChildren`, `Child` (re-exported from `hono/jsx`)
 
 ## `htmlContent()`
 
 Creates a standard OpenAPI content object for `text/html` responses.
 
-`Source ->` [`packages/core/src/utilities/jsx.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/utilities/jsx.utility.ts)
+`Source ->` [`packages/core-server/src/utilities/jsx.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/utilities/jsx.utility.ts)
 
 ```typescript
 const htmlContent = (opts: { description: string; required?: boolean }) => ({
@@ -49,9 +49,9 @@ An OpenAPI content configuration object: `description`, `content['text/html'].sc
 
 ## `htmlResponse()`
 
-Creates a standard OpenAPI response object for HTML endpoints: a success (`200`) HTML response plus a JSON error response for `4xx | 5xx` status codes using `ErrorSchema`.
+Creates a standard OpenAPI response object for HTML endpoints. It pairs a success (`200`) HTML response with a JSON error response for `4xx | 5xx` status codes using `ErrorSchema`.
 
-`Source ->` [`packages/core/src/utilities/jsx.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/utilities/jsx.utility.ts)
+`Source ->` [`packages/core-server/src/utilities/jsx.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/utilities/jsx.utility.ts)
 
 ```typescript
 const htmlResponse = (opts: { description: string; required?: boolean }) => ({
@@ -91,7 +91,7 @@ this.defineRoute({
 
 Defines and registers a JSX/HTML route in a single call - the JSX counterpart of `defineRoute()`.
 
-`Source ->` [`packages/core/src/base/controllers/rest/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/controllers/rest/base.ts)
+`Source ->` [`packages/core-server/src/base/controllers/rest/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/controllers/rest/base.ts)
 
 ```typescript
 defineJSXRoute<RouteConfig extends IAuthRouteConfig, ResponseType = unknown>(opts: {
@@ -111,7 +111,7 @@ defineJSXRoute<RouteConfig extends IAuthRouteConfig, ResponseType = unknown>(opt
 
 `defineJSXRoute` is `defineRoute` with one difference: it builds the route configuration through `getJSXRouteConfigs` instead of `getRouteConfigs`.
 
-`Source ->` [`packages/core/src/base/controllers/rest/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/controllers/rest/abstract.ts)
+`Source ->` [`packages/core-server/src/base/controllers/rest/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/controllers/rest/abstract.ts)
 
 ```typescript
 getJSXRouteConfigs<RouteConfig extends IAuthRouteConfig>(opts: { configs: RouteConfig }) {
@@ -129,9 +129,9 @@ getJSXRouteConfigs<RouteConfig extends IAuthRouteConfig>(opts: { configs: RouteC
 }
 ```
 
-- **Default response merged in first.** `htmlResponse({ description: 'HTML page' })` is the base object; your own `responses` is merged over it with `Object.assign`, so any status code you declare (typically `200`) overrides the default entry with the same key.
+- **Default response merged in first.** `htmlResponse({ description: 'HTML page' })` is the base object. Your own `responses` is merged over it with `Object.assign`, so any status code you declare (typically `200`) overrides the default entry with the same key.
 - **Everything else matches `defineRoute`.** Auth middleware, tags (`this.scope` is always appended), and OpenAPI security are built the same way as JSON routes via `buildRouteMiddlewares`.
-- **Handler contract is unchanged.** The handler still returns whatever `c.html(...)` produces (a `Response`) - `defineJSXRoute` only changes how the route's OpenAPI shape is computed, not how the handler runs.
+- **Handler contract is unchanged.** The handler still returns whatever `c.html(...)` produces (a `Response`). `defineJSXRoute` only changes how the route's OpenAPI shape is computed, not how the handler runs.
 
 ## JSX setup
 
@@ -148,7 +148,7 @@ getJSXRouteConfigs<RouteConfig extends IAuthRouteConfig>(opts: { configs: RouteC
 }
 ```
 
-Verified in [`packages/core/tsconfig.json`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/tsconfig.json) and the JSX example app's [`examples/rpc-api-server/tsconfig.json`](https://github.com/VENIZIA-AI/ignis/blob/main/examples/rpc-api-server/tsconfig.json).
+Verified in [`packages/core-server/tsconfig.json`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/tsconfig.json) and the JSX example app's [`examples/rpc-api-server/tsconfig.json`](https://github.com/VENIZIA-AI/ignis/blob/main/examples/rpc-api-server/tsconfig.json).
 
 ### Component types
 

package/content/references/utilities/jsx.md

@@ -127,5 +127,5 @@ this.defineJSXRoute({
 
 **Files:**
 
-- [`packages/core/src/utilities/jsx.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/utilities/jsx.utility.ts) - `htmlContent`, `htmlResponse`
-- [`packages/core/src/base/controllers/rest/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/controllers/rest/base.ts) - `defineJSXRoute`
+- [`packages/core-server/src/utilities/jsx.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/utilities/jsx.utility.ts) - `htmlContent`, `htmlResponse`
+- [`packages/core-server/src/base/controllers/rest/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/controllers/rest/base.ts) - `defineJSXRoute`