Configuration Reference

Status: v1.23 (single source of truth for every config key) Owner: datapipelines.co core Last updated: 2026-09-17

1. Purpose

Every configuration key for datapipelines.co, in one place. Environment variables, YAML paths, defaults, and descriptions. A developer or operator should never need to search across 15 specs to find a config key.

Authority rule: this document is the ONLY place a configuration key is defined. Other specs reference keys by name and link here — they never restate defaults or introduce keys of their own. A key that does not appear in this document does not exist. (Enforced by scripts/docs-audit.sh.)

Naming rules:

• YAML paths carry explicit units as suffixes: -seconds, -minutes, -hours, -days, -ms, -bytes, -mb, -rows.
• Env var names are derived mechanically: datapipelines. prefix → DATAPIPELINES_, then the YAML path upper-snake-cased. Example: datapipelines.executor.node-query-timeout-seconds → DATAPIPELINES_EXECUTOR_NODE_QUERY_TIMEOUT_SECONDS. No abbreviations, no exceptions — the env var is always derivable from the YAML path.

2. Required Configuration

The app will not start without these. Fail-fast on missing values.

OIDC provider configuration is also required — at least one provider must be configured in datapipelines.auth.oidc.providers (in application.yml). Each provider requires client-id, client-secret, and issuer-uri. The client-id and client-secret are typically referenced from env vars. See Auth spec §11.1 for the full format.

The specific env var names depend on which provider(s) the deployment chooses. Examples:

The deployment defines these env var names in application.yml — they're not hardcoded by the app. (OIDC provider env vars are the one deliberate exception to the naming derivation rule in §1, since the deployment names them.)

3. Optional Configuration (with defaults)

3.1 Redis

Env vars are derived per §1 (e.g. DATAPIPELINES_REDIS_PORT) and are omitted from the tables below for brevity.

3.2 Executor

Three budgets, one precedence (the same table appears in pipeline-contract §4.11 and dag-executor §5.3):

Instances are moderate, so the statement bound must be sized for a COLD read, not a warm one (156, #2). This deployment is expected to run as several instances of moderate size, not one box with all the memory a query could want — so a LAKE engine sharing that box's memory with everything else keeps less of the object store cached, and a query that lands on an instance whose cache is cold re-reads from S3 at network speed instead of from RAM. The per-dialect operator default above exists for exactly that reason, sized to the cold read of the largest scan a deployment runs, not the warm one a developer's laptop measures. When cold reads on a given box routinely approach the default, the right levers are raising node-query-timeout-seconds-by-dialect.lake (this section) or raising the engine's own memory-limit (§3.25) so more of the data stays cached between queries — see also #141 on the shared-engine memory budget these two knobs both bound against.

Read downward. The statement bound is the driver's and drivers honour it unevenly — measured on the shipped drivers (108 §1), which is precisely why the middle row exists. The precedence is a recommendation, not a cross-key constraint: nothing refuses a configuration that inverts it, because every inversion is harmless. A node deadline above the execution's is simply never reached — the outer bound fires first and reports pipeline.execution.timeout. One below the statement timeout is stronger, not broken: the executor stops the node before the driver would have, which is the whole point of owning a bound above the driver's. What a cross-key refusal would reliably do instead is turn "I lowered execution-timeout-seconds for this deployment" into a startup crash. node-timeout-max-seconds is deliberately NOT constrained against the execution timeout — it bounds what an author may ASK for, not what a run may take.

3.3 Staging (tempdb)

max-connections is capacity, not parallelism. It bounds how many tempdb operations of ONE execution can be inside H2 at the same instant; it creates no extra eligible DAG nodes (executor.max-parallel-nodes decides those) and promises no speedup — H2 keeps its own transaction, row and catalog locks, so two nodes touching one table still serialise inside the engine. Set it lower than max-parallel-nodes and nodes queue safely for a connection; set it higher and the surplus is never opened. Aggregate cost: every connection is one H2 session with its own query working memory, and max-concurrent-executions-per-instance executions can each hold up to this many — the staged tables themselves are shared by the connections of one execution and are not multiplied. Session state (SET SCHEMA, SET @var, local temporary tables, an open transaction) is per operation and is reset when a connection is returned; a node must not rely on it from another node — express data flow through ordinary tables and depends_on, whatever the cap (Staging §9.2).

max-memory-mb is a per-execution THRESHOLD over a JVM-WIDE measurement — not an isolated per-execution budget. The guard samples used heap for the WHOLE JVM (in-process totalMemory − freeMemory, Staging §8.2), so every concurrent execution's check reads the same shared number: one heavy execution can trip a lighter one's check, and the guard is a sampled circuit breaker — not a hard reservation, and no guarantee against OOM. Size from the demand side instead: N concurrent executions really do hold N tempdbs' tables, indexes and query working memory at once, so worst-case heap DEMAND stays max-memory-mb × datapipelines.executor.max-concurrent-executions-per-instance per instance (050/R2: the multiplier is per-instance; N replicas multiply it again — Deployment §6.6), and -Xmx plus the container limit must cover that with baseline headroom — an underestimate ends in the §8.4 JVM backstop, not in a clean pipeline.staging.memory_limit_exceeded. A per-execution accounting redesign is a separately decided follow-up, not this guard's promise.

Startup says the arithmetic out loud (108 §C). ConfigValidator logs ONE warn line at startup when max-concurrent-executions-per-instance × max-memory-mb > 0.8 × the JVM's max heap, naming all three numbers and the ratio. It is a WARNING and not a refusal, deliberately: the budget is a ceiling each execution MAY reach, not one it will, and a deployment whose pipelines stage tens of megabytes is right to run 100 slots against a 1 GB budget — refusing that would break every default installation. What an operator cannot do is notice the arithmetic unaided, since the two keys live in different sections of this document and neither used to mention the other. Above the ratio, the per-execution limit would be enforced by an OOM rather than by pipeline.staging.memory_limit_exceeded.

A pipeline's settings.tempdb.config.max_memory_mb override is clamped to ≤ this value — it may lower the operator's ceiling for that pipeline, never raise it. Save-time validation only checks > 0, so without the clamp an author could declare an arbitrarily large budget and disable the only ceiling the executor's withConnection paths have (DAG Executor §9).

3.4 Auth

3.5 Results

Every completed execution's caller result is stored in Redis and read through the result cursor (REST API §7).

3.6 SSE

3.7 Rate Limiting

Limits are per user (an API key inherits its owner's budget — minting more keys does not raise the limit).

There is deliberately no fail-open key. When the limiter's Redis is unreachable the limiter refuses the request (429 rate_limit.unavailable, REST API §12.3); a per-deployment toggle would only ever be reached for at exactly the moment the refusal is the correct answer.

3.8 Idempotency

3.9 Templates

3.10 UI

3.11 Execution History

3.12 Audit

3.13 Server

3.14 Framework wiring keys

These framework key paths appear in application.yml as internal wiring. They are listed here so the §1 authority sentence stays literally true. With the single exception of management.server.port (below), operators do not set them and deployments must not override them:

Operator-tunable exception:

3.15 Observability

3.16 Pipelines

3.17 Workspaces

Workspaces are created by super admins (auth.md §4.2/§5.6, §12). The one workspace the product ships is demo, and a user with no membership becomes a viewer of it on first login.

Removed in RBAC round 1 (provisioning-mode, open-join). Capability moved onto the workspace membership, and with it went the modes that decided who could create a workspace: auto-per-user (a personal workspace per login), self-serve (anyone creates) and closed (admin only), plus open-join (anyone self-joins). Both keys are refused BY NAME at startup (§7) rather than ignored — a deployment that still says auto-per-user is a deployment expecting a personal workspace per user, and silently giving it something else is how an operator finds out from a user. Delete the key; there is no replacement to set, because the behaviour is no longer a knob.

3.18 Bootstrap

Config-declared content applied at startup (design 2026-08-16-sample-data §6/§6.1). Both keys name files already on the container's filesystem — the app never fetches an artifact at runtime; downloading and verifying artifacts is a deployment step (D5) — and for both, unset (or empty) means the feature is off. There is no separate enable flag to disagree with the path.

Both values are comma-separated LISTS of paths (one entry per sample-data family; the demo profiles compose the list from the active families). A single value with no comma is the one-file shape older deployments ship — the list semantics are backward compatible by construction. Empty entries (a leading comma when a family is off, or a whitespace-only entry) are dropped, so a list built by shell conditional expansion never turns the feature on by accident. The files are processed in declared order.

Cross-key rule: datasources-file set while datapipelines.auth.bootstrap-admin-email is unset is a startup refusal naming both keys. Bootstrap-registered datasources are created_by that user, and registration runs before anyone has logged in, so the row is pre-provisioned from that address (Auth §4.4). examples-file carries no such rule: seeding runs at first login, under the identity of the user logging in.

Cross-key rule (examples-file): examples-file set while datapipelines.workspaces.provisioning-mode is anything but auto-per-user — including its shipped default self-serve — is a startup refusal naming both keys. Seeding runs only when first login provisions a personal workspace; under any other mode the file is read and validated at startup and then never seeded, silently. Set the mode, or unset the file.

3.19 Deployment

The deployment-role settings (Versioning §5.5) — grouped one-per-concern like auth, executor, staging.

Renamed in 075. datapipelines.deployment.name — the deployment LABEL — is now datapipelines.env (DATAPIPELINES_ENV), documented in §3.23 beside the posture it is deliberately separate from. The old key is honoured for one release: set alone it still names the deployment and startup logs event=config.deployment_name_deprecated; set together with datapipelines.env and disagreeing, startup is refused naming both. See Environments.

Promotion (the deployment-to-deployment channel)

Promotion is one deployment writing RELEASED content into exactly one configured higher environment (Versioning §10). The credential is a server key, not a principal (Versioning §10.6): no users row for the credential and no scope-matrix entry. A deployment may hold the receiver half, the sender half, both, or neither.

The receiver half is now a KEY, and the config value below is DEPRECATED (091). Mint a server-kind API key on the API screen (Auth §7.7) and give it to the sending deployment as its target.server-key. A stored key is everything a config value cannot be: expiring, revocable, listed beside every other credential, rotatable without a restart, and stamped with a last-used time. datapipelines.deployment.promotion.server-key is still accepted for one release so an upgrade does not break an existing pair — and it WARNs at boot when set (§7). Both credentials open the same routes; the receiver tries the configured value first, then the key store.

On the SENDER, the value is whatever the receiver issued: the dpk_<id>.<secret> plaintext of the receiver's server key, shown exactly once at minting. Rotation is then a receiver-side act with no restart anywhere: mint a second server key, set it on the sender, revoke the first. For the deprecated config value, generate it the way every other secret here is — openssl rand -base64 32 — and set it identically on both sides; rotation means restarting both. Either way no user account is involved, so offboarding a human can never break production promotion — a server key's owner is the admin who minted it, and the promotion acts as the system service account regardless (Auth §4.5).

Both keys are bearer secrets. They are never logged, never in an error message, never in an audit details map, and never in a toString(). A receiver records only a truncated SHA-256 fingerprint of the key a push presented, so two keys are distinguishable across a rotation without either being carried.

3.20 Credential key provider

Where the AES data keys for datasources.credential_encrypted come from (Datasources §7.1). The seam exists so a customer's AWS/GCP/Azure/Vault key store is an implementation of a contract, not a change to the crypto — docs/key-providers.md is the guide an implementer works from. Every stored credential carries the key VERSION it was sealed under as its first byte, which is what makes rotation lazy-safe.

Every configured key is a bearer secret. None of them is logged, put in an error message, put in an audit details map, or rendered by a toString() — the §7 violations name the property and the defect, never the value.

Rotating. Generate a key (openssl rand -base64 32), add it as version N+1, set encryption-key-current: N+1, restart. New writes carry N+1; rows written under earlier versions keep decrypting, and are rewritten under the current key the next time their password is saved. Keep the old keys configured until no row still carries their version — Datasources §7.3 has the one SQL query that answers that.

3.21 Organisation

The organisation's own facts — its currency, when its fiscal year starts, which day its week starts on, which timezone "today" means. They are configuration, not pipeline data: identical for every pipeline in the deployment, changed about once a decade, and a value that differs between deployments must be visible in the deployment's yml rather than copied into every body.

Every key here enters every execution's Context as an org_* key — the yml path minus the datapipelines.org. prefix, with dots and dashes as _ (Pipeline Contract §7.2). A node binds :org_currency_symbol; a CALCULATOR node references $org_fiscal_start_date. None of them is a secret, and a pipeline may override any of them by declaring a parameter of the same name.

Env vars follow §1's derivation rule: DATAPIPELINES_ORG_CURRENCY_NAME, DATAPIPELINES_ORG_CURRENCY_SYMBOL, DATAPIPELINES_ORG_FISCAL_START_DATE, DATAPIPELINES_ORG_WEEK_START, DATAPIPELINES_ORG_TIMEZONE.

Restart to change. There is no runtime override and no per-user setting: an org value that could change mid-run would make two nodes of one execution disagree about what year it is. A bad value stops the server (§7) rather than silently defaulting — a wrong fiscal start is a wrong number in every report the deployment produces.

3.22 Published endpoints

The timeout bounds for a released pipeline published as a GET endpoint under /api/x (round 074). timeout-default-seconds is what a publish that names no timeout is stored with; the min/max pair clamps every stored published_endpoints.timeout_seconds at write time, so retuning the bounds later never makes an existing row unreadable — it only changes what the next publish may ask for.

There is deliberately no page-rows-max key here. The DP-Result-Page-Rows request header is one contract across a published endpoint and POST /pipelines/{id}/execute, and both clamp it to datapipelines.result.page-max-rows (§3.5). A second key that had to equal the first would be a second authority for one bound, and an operator who retuned one and not the other would get two different clamps on one documented header.

3.23 Environment and posture

The two variables an organisation sets (round 075). Environments is the page written for the DevOps engineer who deploys this; this section is the key reference.

The environment's NAME belongs to the org; the POSTURE belongs to the product. Organisations have dev, qa, uat, perf, sandbox-eu, prod — any names, any count — and the product must never branch on one: a single-server user honestly writes prod as their label, and the first if (env == "prod") anywhere locks them out of authoring on the only server they have. What the product branches on is a closed, two-valued posture with the documented semantics below, and the org maps each of its environments onto one.

The posture table (normative)

The posture IS the Spring profile

spring.profiles.active is derived from DATAPIPELINES_POSTURE in application.yml, and application-development.yml / application-hardened.yml carry the posture's non-secret defaults (the first two rows above). One variable therefore gives every loader — Compose, a bare java -jar, systemd, Kubernetes, ECS, Nomad — the right defaults, and nothing the product needs lives only in a launcher. Setting SPRING_PROFILES_ACTIVE yourself is unnecessary; a value that disagrees with the posture refuses startup (§7) rather than silently loading one posture's defaults while every posture RULE judges the other. 075 renamed the dev profile to development; a deployment still asking for dev is refused, not ignored.

Nothing lives only in a compose file

The contract is environment variables, in two files: deploy/env/defaults.env (tracked — every non-secret variable this build binds, with the value it ships) and deploy/secrets.env (git-ignored — every credential, plus every override that belongs to this deployment). deploy/secrets.env.example is the template for the second and names every variable you may set. scripts/compose-env-audit.sh — which runs on every ./gradlew build — fails when those files, deploy/compose.yml and application.yml disagree about which variables exist or what they default to, and when a variable is declared in both tracked files or in neither. Settings are tracked in the repo; secrets never are.

3.24 Lake datasource engine limits (dp-lake)

A LAKE datasource runs its queries on the app's own box — DuckDB is embedded in the app process, so its memory, threads and spill disk are operator knobs, not someone else's infrastructure. These are datasource properties (properties.dialect.*, set per datasource through the REST API or a bootstrap datasources file — Datasources §12.1), not datapipelines.* keys: they do not belong in application.yml or an env file, they are validated per key at save time (an unknown key or a bad value is refused), and a change takes effect at the datasource's next pool build, with no app restart. The existing execution bounds apply unchanged beside them: the result row cap and node-query-timeout-seconds.

Scope: one engine per datasource pool, shared by its connections (152). Each LAKE datasource pool build opens ONE embedded DuckDB instance that every pooled connection joins (Datasources §5.2); the three properties below are applied once to that instance and are ONE budget for the pool — properties.hikari.maximumPoolSize does not multiply them, and concurrent queries on the datasource share them. Size the box for memory_limit × the number of LAKE datasources on the instance (each has its own engine), with headroom for a retiring pool's engine while it drains after a datasource save. The engine's file cache lives with that instance, so a warm lake stays warm across HikariCP's routine connection replacement; a datasource save or a lake-table registration rebuilds the pool and starts a fresh engine, cold.

For the supported anonymous in-memory URLs (jdbc:duckdb: and jdbc:duckdb::memory:), the default spill directory belongs to one engine initialization: pooled connections share it, while independent in-memory pool generations receive different paths. DuckDB creates it lazily when spilling and removes it on normal instance shutdown. The parent directory must exist, be writable by the application user, and have enough disk space for concurrent queries; the Helm chart provides disk-backed /tmp. A bare JVM can select the parent with -Djava.io.tmpdir=/writable/path. An explicit override is used exactly as supplied: dedicate that directory to the engine, keep unrelated files out, and avoid sharing it between independent engines or overlapping generations. Named in-memory and file-backed URLs can join an existing JVM-wide engine; when no override is supplied, its current spill setting is left untouched. Configure a writable path explicitly for those URLs, consistently across every pool sharing that engine. A crash or a driver that refuses shutdown can leave spill files behind; reclaim them only after the owning process has stopped.

threads is deliberately left unset, and the measurement is why — though not the way the hypothesis expected (108 §C). In-process DuckDB shares the JVM's CPUs with the executor, so the obvious guard is to cap the engine's worker threads; max(2, cores/2) was the proposal. Measured on a 10-core box as the median of 5 PAIRED runs (each pair times the scan alone and then immediately under load, so a drifting box moves both numbers):

A 0.92× is a scan that ran FASTER under load than alone, which is not a result — it is the noise floor. On a box shared with other work the contention effect is smaller than the measurement's own variance, and an earlier single-run shape produced swings from 1.13× to 1.82× for the same cell. So the honest reading is: no evidence for a thread cap, and none against one either — the effect this knob would manage is not resolvable here. The default therefore stays unset (DuckDB's own scheduler handles oversubscription), an operator who needs the engine bounded sets threads explicitly, and anyone who wants to settle it should re-run scripts/measure/03-pressure.sh on a dedicated box.

What the runs DO agree on: a lake read on a busy box loses on the order of 10 % or more, and no threads value observed changed that.

Two statements are emitted on every lake connection regardless of these keys: SET memory_limit = '<explicit-or-default>' (there is always a budget) and SET preserve_insertion_order = false — insertion order costs memory and temp-file discipline the engine would otherwise spend on a guarantee a read-only lake never asks for. It is not a knob: a lake is a read connector, and making the trade configurable would only let an operator buy back a guarantee no query path uses.

3.25 DuckDB extension directory (dp-lake)

A LAKE datasource whose data is on S3 needs DuckDB's httpfs and aws extensions, and the Iceberg catalog kinds additionally need iceberg (which itself requires avro). Where those binaries come from is this key. It is an operator-level key — one value for the whole deployment, restart-to-change — deliberately NOT a per-datasource properties.dialect.* entry: which extension files the engine may load is a deployment security posture, not row data.

Operator instruction: set DATAPIPELINES_DUCKDB_MEMORY_LIMIT=8GB in deploy/secrets.env (or the deployment's own env file) and restart the app — the value is read once at wiring, not per pool build, so every LAKE datasource without its own properties.dialect.memory_limit picks it up on its next pool build after the restart (a fresh cold engine; the first query after restart is cold, the next warm). Confirm it took effect over a LAKE connection with SELECT current_setting('memory_limit') (reports the exact configured value, e.g. 8.0GB) or SELECT * FROM duckdb_memory() (the engine's own memory-accounting view, docs/staging.md §"Memory accounting" — its buffer manager budget reflects the same limit).

Set (the shipped image): every lake connection runs SET extension_directory = '<dir>' followed by bare LOADs — LOAD httpfs; LOAD aws for catalog.kind: s3, plus LOAD avro; LOAD iceberg for the Iceberg kinds — and never an INSTALL. In DuckDB v1.5.5 LOAD strictly loads already-present files (no download code path runs at all — measured in the 089 §7.3 spike against this exact base image with --network none), so a lake pool connects with zero egress. The published image bundles the four extensions for DuckDB core v1.5.5 under /opt/duckdb/extensions/v1.5.5/<platform>/, the <platform> following the image build's architecture (linux_amd64 or linux_arm64 — the Dockerfile maps BuildKit's TARGETARCH; hard-coding one architecture leaves the other LOAD-only against an empty directory, a pool-init failure at connect — found by the 089 live gate), and exports this variable from the Dockerfile; deploy/compose.yml defaults to the same path. The bundle adds ~108 MB uncompressed to the image (~39 MB downloaded at build). A hardened dp-lake deployment with the bundled directory needs no egress to extensions.duckdb.org at all.

Unset (a bare java -jar, a developer machine): the adapter keeps its explicit INSTALL+LOAD pairs, unchanged. The first INSTALL of each extension downloads it from extensions.duckdb.org — once per extension per container filesystem (the engine's default ~/.duckdb/extensions cache), so an ephemeral container re-downloads on every fresh start.

Version coupling: the bundled binaries are valid for exactly one DuckDB core version. The pinned duckdb_jdbc is 1.5.5.1, whose bundled core reports v1.5.5 — the directory's v1.5.5 component is the CORE version, not the JDBC patch version. A duckdb_jdbc upgrade must re-download all four extensions and rename the directory accordingly (the Dockerfile pins both in one ARG).

3.26 Datasource pools

How long a retired connection pool may keep connections out before it is closed regardless (Datasources §5.2, round 094). A datasource that is edited or deleted has its pool taken out of the live map at once and soft-evicted; the pool itself is closed when the statements already running on it finish — or at this ceiling, whichever comes first, so a genuinely hung statement cannot pin a deleted datasource's pool forever. Each hard close logs one WARN naming the datasource and the connections it took down, and increments datapipelines.datasource.pool.hard_closed (Observability §4.1).

Why the default is derived rather than a number. The ceiling and the node query timeout are the same fact seen twice: a deployment that raises node-query-timeout-seconds to 600 and leaves a literal 90 here would start hard-closing pools out from under statements that are still legitimately running, and nothing would tell it. Deriving makes the two move together; an explicit value opts out.

3.27 Mail

Outbound mail (137, Auth §5A.8) — the SMTP server this deployment sends its two notices through: the welcome / password-reset mail to a local user (the login URL and the one-time password) and the "New user" notice to sys-ops (no password). Any SMTP server: traditional host, port, username, password. Postmark's SMTP endpoint is one such server, and its message-stream header is the only vendor-shaped knob.

Mail is enabled exactly when it is configured — there is no enabled key. Mail is on iff host AND from are both set. A flag that could disagree with the fields it summarises is the YAML-boolean trap the house has already logged; "configured" is the only honest definition of "on" for an outbound adapter. Every half-configured shape refuses startup naming the field (§7).

Cross-key rule: mail on requires datapipelines.auth.base-url (§3.4) — the welcome mail carries the login URL, which is built from it and never from a request's origin (Auth §5.2).

What the admin screen shows follows from the derivation: with mail on, the create-user and reset-password actions no longer display the one-time password — it went to the user, and the screen says so with the send's outcome; with mail off they show it as before (UI §4.12).

4. Precedence

Resolution order for any key, highest first:

1. Environment variable (via the ${ENV:default} placeholder).
2. Active profile YAML — the POSTURE file, application-development.yml or application-hardened.yml (§3.23).
3. Base application.yml default.

Under a loader that assembles env files (docker compose --env-file, set -a; . file), the files are read in order and the LAST one wins; app.sh passes deploy/env/defaults.env, then deploy/secrets.env — secrets last, so a value an operator sets there always wins. Two files, that order, under every loader.

Two documented per-entity overrides sit above global config at runtime (they are data, not config):

• Pipeline settings.tempdb.config.max_memory_mb overrides datapipelines.staging.h2.max-memory-mb for that pipeline.
• Datasource query_timeout_seconds overrides datapipelines.executor.node-query-timeout-seconds for nodes on that datasource.

5. Full application.yml Template

Complete — a deployment assembled from this block gets the framework wiring (§3.14) too. Omitting the management: block in particular re-serves the actuator on the application port, which is exactly the exposure the management port exists to prevent.

spring:
  application:
    name: datapipelines
  profiles:
    # §3.23 — the POSTURE selects the profile that carries its defaults. Empty means no
    # profile, and the base defaults below ARE the `development` column.
    active: ${DATAPIPELINES_POSTURE:}
  datasource:
    url: ${SPRING_DATASOURCE_URL}
    username: ${SPRING_DATASOURCE_USERNAME}
    password: ${SPRING_DATASOURCE_PASSWORD}
    hikari:
      maximum-pool-size: ${SPRING_DATASOURCE_HIKARI_MAXIMUM_POOL_SIZE:10}
  data:
    redis:                       # §3.14 bridge — operators set only DATAPIPELINES_REDIS_*
      host: ${DATAPIPELINES_REDIS_HOST}
      port: ${DATAPIPELINES_REDIS_PORT:6379}
      password: ${DATAPIPELINES_REDIS_PASSWORD:}
  flyway:
    enabled: true
    locations: classpath:db/migration
    baseline-on-migrate: false

server:
  port: ${SERVER_PORT:8080}

management:                      # §3.14 — actuator on the management port ONLY
  server:
    port: ${MANAGEMENT_SERVER_PORT:9090}
    address: ${MANAGEMENT_SERVER_ADDRESS:127.0.0.1}   # loopback default; 0.0.0.0 only with a NetworkPolicy
  endpoints:
    web:
      exposure:
        include: "health"        # never "" and never exclude:"*" — see §3.14
  health:
    diskspace:
      enabled: false

datapipelines:
  redis:
    host: ${DATAPIPELINES_REDIS_HOST}
    port: ${DATAPIPELINES_REDIS_PORT:6379}
    password: ${DATAPIPELINES_REDIS_PASSWORD:}

  jwt:
    secret: ${DATAPIPELINES_JWT_SECRET}

  db:
    key-provider: ${DATAPIPELINES_DB_KEY_PROVIDER:env}
    encryption-key: ${DATAPIPELINES_DB_ENCRYPTION_KEY}
    # Rotation (§3.20) — unset by default; a declared empty map would bind over the environment.
    # encryption-keys:
    #   2: ${DATAPIPELINES_DB_ENCRYPTION_KEY_V2}
    # encryption-key-current: 2

  auth:
    oidc:
      providers:
        # client-id defaulting to empty = the entry is IGNORED with a WARN (§7);
        # a local-accounts-only deployment starts with zero OIDC providers.
        - name: google
          client-id: ${GOOGLE_CLIENT_ID:}
          client-secret: ${GOOGLE_CLIENT_SECRET:}
          issuer-uri: https://accounts.google.com
          display-name: "Sign in with Google"
        - name: microsoft
          client-id: ${MICROSOFT_CLIENT_ID:}
          client-secret: ${MICROSOFT_CLIENT_SECRET:}
          issuer-uri: https://login.microsoftonline.com/common/v2.0
          display-name: "Sign in with Microsoft"
        # Add more providers as needed (Okta, Auth0, Keycloak, etc.)
    jwt:
      ttl-hours: ${DATAPIPELINES_AUTH_JWT_TTL_HOURS:8}
    allowlist:
      domains: ${DATAPIPELINES_AUTH_ALLOWLIST_DOMAINS:}
    api-keys:
      cache-ttl-seconds: ${DATAPIPELINES_AUTH_API_KEYS_CACHE_TTL_SECONDS:60}
      default-scopes: ${DATAPIPELINES_AUTH_API_KEYS_DEFAULT_SCOPES:read}
    rate-limit:
      login-per-minute: ${DATAPIPELINES_AUTH_RATE_LIMIT_LOGIN_PER_MINUTE:10}
    trusted-proxies: ${DATAPIPELINES_AUTH_TRUSTED_PROXIES:}
    local:
      enabled: ${DATAPIPELINES_AUTH_LOCAL_ENABLED:false}
      bootstrap-password-hash: ${DATAPIPELINES_AUTH_LOCAL_BOOTSTRAP_PASSWORD_HASH:}
      bootstrap-password: ${DATAPIPELINES_AUTH_LOCAL_BOOTSTRAP_PASSWORD:}
      lockout:
        max-failures: ${DATAPIPELINES_AUTH_LOCAL_LOCKOUT_MAX_FAILURES:5}
        duration-minutes: ${DATAPIPELINES_AUTH_LOCAL_LOCKOUT_DURATION_MINUTES:15}
    cookie-secure: ${DATAPIPELINES_AUTH_COOKIE_SECURE:}
    allow-local-only: ${DATAPIPELINES_AUTH_ALLOW_LOCAL_ONLY:false}

  executor:
    max-parallel-nodes: ${DATAPIPELINES_EXECUTOR_MAX_PARALLEL_NODES:4}
    max-concurrent-executions-per-user: ${DATAPIPELINES_EXECUTOR_MAX_CONCURRENT_EXECUTIONS_PER_USER:10}
    # Per-INSTANCE ceiling (050/R2); the deprecated `max-concurrent-executions-global` alias is
    # deliberately absent here — it binds only when an operator still sets it.
    max-concurrent-executions-per-instance: ${DATAPIPELINES_EXECUTOR_MAX_CONCURRENT_EXECUTIONS_PER_INSTANCE:100}
    node-query-timeout-seconds: ${DATAPIPELINES_EXECUTOR_NODE_QUERY_TIMEOUT_SECONDS:60}
    execution-timeout-seconds: ${DATAPIPELINES_EXECUTOR_EXECUTION_TIMEOUT_SECONDS:600}
    node-timeout-seconds: ${DATAPIPELINES_EXECUTOR_NODE_TIMEOUT_SECONDS:300}
    node-timeout-max-seconds: ${DATAPIPELINES_EXECUTOR_NODE_TIMEOUT_MAX_SECONDS:900}
    cancel-grace-seconds: ${DATAPIPELINES_EXECUTOR_CANCEL_GRACE_SECONDS:5}
    source-fetch-size: ${DATAPIPELINES_EXECUTOR_SOURCE_FETCH_SIZE:1000}
    progress-write-interval-seconds: ${DATAPIPELINES_EXECUTOR_PROGRESS_WRITE_INTERVAL_SECONDS:5}
    progress-sample-interval-seconds: ${DATAPIPELINES_EXECUTOR_PROGRESS_SAMPLE_INTERVAL_SECONDS:1}
    heartbeat-seconds: ${DATAPIPELINES_EXECUTOR_HEARTBEAT_SECONDS:15}

  pipelines:
    max-composition-depth: ${DATAPIPELINES_PIPELINES_MAX_COMPOSITION_DEPTH:5}

  deployment:
    authoring-enabled: ${DATAPIPELINES_DEPLOYMENT_AUTHORING_ENABLED:true}
    promotion:
      server-key: ${DATAPIPELINES_DEPLOYMENT_PROMOTION_SERVER_KEY:}
      target:
        base-url: ${DATAPIPELINES_DEPLOYMENT_PROMOTION_TARGET_URL:}
        server-key: ${DATAPIPELINES_DEPLOYMENT_PROMOTION_TARGET_KEY:}

  workspaces:
    member-datasources-enabled: ${DATAPIPELINES_WORKSPACES_MEMBER_DATASOURCES_ENABLED:true}

  staging:
    h2:
      mode: ${DATAPIPELINES_STAGING_H2_MODE:PostgreSQL}
      max-memory-mb: ${DATAPIPELINES_STAGING_H2_MAX_MEMORY_MB:1024}
      insert-batch-size: ${DATAPIPELINES_STAGING_H2_INSERT_BATCH_SIZE:1000}
      result-batch-size: ${DATAPIPELINES_STAGING_H2_RESULT_BATCH_SIZE:10000}
      query-timeout-seconds: ${DATAPIPELINES_STAGING_H2_QUERY_TIMEOUT_SECONDS:60}
      max-connections: ${DATAPIPELINES_STAGING_H2_MAX_CONNECTIONS:4}

  result:
    ttl-default-seconds: ${DATAPIPELINES_RESULT_TTL_DEFAULT_SECONDS:300}
    ttl-min-seconds: ${DATAPIPELINES_RESULT_TTL_MIN_SECONDS:60}
    ttl-max-seconds: ${DATAPIPELINES_RESULT_TTL_MAX_SECONDS:3600}
    max-size-bytes: ${DATAPIPELINES_RESULT_MAX_SIZE_BYTES:104857600}
    page-size-rows: ${DATAPIPELINES_RESULT_PAGE_SIZE_ROWS:1000}
    page-max-rows: ${DATAPIPELINES_RESULT_PAGE_MAX_ROWS:100000}

  sse:
    heartbeat-interval-seconds: ${DATAPIPELINES_SSE_HEARTBEAT_INTERVAL_SECONDS:15}
    disconnect-grace-seconds: ${DATAPIPELINES_SSE_DISCONNECT_GRACE_SECONDS:30}
    max-streams-per-user: ${DATAPIPELINES_SSE_MAX_STREAMS_PER_USER:50}

  rate-limit:
    requests-per-second: ${DATAPIPELINES_RATE_LIMIT_REQUESTS_PER_SECOND:100}
    requests-per-minute: ${DATAPIPELINES_RATE_LIMIT_REQUESTS_PER_MINUTE:1000}

  idempotency:
    ttl-seconds: ${DATAPIPELINES_IDEMPOTENCY_TTL_SECONDS:86400}

  templates:
    cache-size: ${DATAPIPELINES_TEMPLATES_CACHE_SIZE:500}
    render-timeout-ms: ${DATAPIPELINES_TEMPLATES_RENDER_TIMEOUT_MS:5000}

  ui:
    theme: ${DATAPIPELINES_UI_THEME:dark}

  executions:
    event-retention-days: ${DATAPIPELINES_EXECUTIONS_EVENT_RETENTION_DAYS:7}
    stale-timeout-minutes: ${DATAPIPELINES_EXECUTIONS_STALE_TIMEOUT_MINUTES:60}

  audit:
    retention-days: ${DATAPIPELINES_AUDIT_RETENTION_DAYS:365}

  observability:
    tracing:
      enabled: ${DATAPIPELINES_OBSERVABILITY_TRACING_ENABLED:false}
    logging:
      format: ${DATAPIPELINES_OBSERVABILITY_LOGGING_FORMAT:json}

  bootstrap:
    datasources-file: ${DATAPIPELINES_BOOTSTRAP_DATASOURCES_FILE:}
    examples-file: ${DATAPIPELINES_BOOTSTRAP_EXAMPLES_FILE:}

  # §3.21 — organisation facts. Appended AFTER the whole datapipelines: tree, never inserted
  # between its children: a 2-space block placed mid-tree re-parents whatever follows it.
  org:
    currency:
      name: ${DATAPIPELINES_ORG_CURRENCY_NAME:Dollar}
      symbol: ${DATAPIPELINES_ORG_CURRENCY_SYMBOL:$}
    fiscal-start-date: ${DATAPIPELINES_ORG_FISCAL_START_DATE:01-01}
    week-start: ${DATAPIPELINES_ORG_WEEK_START:monday}
    timezone: ${DATAPIPELINES_ORG_TIMEZONE:UTC}
  endpoints:
    timeout-default-seconds: ${DATAPIPELINES_ENDPOINTS_TIMEOUT_DEFAULT_SECONDS:30}
    timeout-min-seconds: ${DATAPIPELINES_ENDPOINTS_TIMEOUT_MIN_SECONDS:1}
    timeout-max-seconds: ${DATAPIPELINES_ENDPOINTS_TIMEOUT_MAX_SECONDS:300}
  # §3.23 — appended after the whole datapipelines: tree, never inserted between two of
  # its children (a 2-space block placed mid-tree closes its predecessor and silently
  # re-parents whatever follows it).
  env: ${DATAPIPELINES_ENV:local}
  posture: ${DATAPIPELINES_POSTURE:}
  demo: ${DATAPIPELINES_DEMO:}

  # §3.25 — the LAKE engine's bundled extension directory. Empty = INSTALL+LOAD with egress
  # (a bare jar has nothing bundled); the shipped image exports the variable itself.
  duckdb:
    extension-directory: ${DATAPIPELINES_DUCKDB_EXTENSION_DIRECTORY:}
    # §3.25 — the operator default memory_limit every LAKE engine build gets when a
    # datasource declares none. Empty = the derived 25%-of-container default.
    memory-limit: ${DATAPIPELINES_DUCKDB_MEMORY_LIMIT:}

  # §3.27 — outbound mail. NO `enabled` key: on exactly when host AND from are set.
  mail:
    host: ${DATAPIPELINES_MAIL_HOST:}
    port: ${DATAPIPELINES_MAIL_PORT:587}
    username: ${DATAPIPELINES_MAIL_USERNAME:}
    password: ${DATAPIPELINES_MAIL_PASSWORD:}
    starttls: ${DATAPIPELINES_MAIL_STARTTLS:true}
    from: ${DATAPIPELINES_MAIL_FROM:}
    reply-to: ${DATAPIPELINES_MAIL_REPLY_TO:}
    ops-to: ${DATAPIPELINES_MAIL_OPS_TO:}
    message-stream: ${DATAPIPELINES_MAIL_MESSAGE_STREAM:}

Note: OIDC provider config is in the app's own YAML namespace (datapipelines.auth.oidc.providers), NOT in Spring Security's native spring.security.oauth2.client.* namespace. Our OidcConfig bean reads this list and builds ClientRegistration objects programmatically. See Auth spec §5.2.

Internal binding note (Redis, 2026-08-07): Spring Boot's Redis autoconfiguration reads spring.data.redis.*, so application.yml carries an internal bridge (spring.data.redis.host: ${DATAPIPELINES_REDIS_HOST} etc.) mapping the canonical datapipelines.redis.* keys onto it. This introduces NO operator-facing keys — operators set only the DATAPIPELINES_REDIS_* variables defined here. The bridge is an implementation detail and may be replaced by an explicit LettuceConnectionFactory bound to @ConfigurationProperties("datapipelines.redis").

6. Posture Profiles (application-development.yml / application-hardened.yml)

The POSTURE's non-secret defaults (§3.23). spring.profiles.active is derived from DATAPIPELINES_POSTURE in application.yml, so setting that one variable loads the right file under every loader — Compose, a bare java -jar, systemd, Kubernetes. Setting SPRING_PROFILES_ACTIVE yourself is unnecessary, and a value that disagrees with the posture refuses startup (§7).

These files carry POSTURE, never INFRASTRUCTURE. Before 075 this section documented application-dev.yml, which was really a LAPTOP file: localhost:5434, console logging, one developer's host ports. An org's dev environment on Kubernetes runs the development posture too and must not inherit any of that. The laptop's values are ordinary lines in deploy/env/defaults.env, which every loader reads (DEVELOPMENT.md §2/§4).

And they carry the posture's defaults ALONE (081). No env file may name DATAPIPELINES_DEPLOYMENT_AUTHORING_ENABLED or DATAPIPELINES_AUTH_COOKIE_SECURE: there is one tracked settings file, it is loaded for every posture, and an environment variable outranks a profile — so a value there would be one posture's answer imposed on both. 075 did exactly that and a hardened stack booted with authoring=on. deploy/compose.yml passes those two in Compose's valueless form (DATAPIPELINES_AUTH_COOKIE_SECURE:, nothing after the colon), the only form that leaves a variable unset rather than empty — an empty variable outranks a profile just as a set one does. An operator can still override either in deploy/secrets.env. PostureDefaultsSpecDriftTest and compose-env-audit.sh check 7 hold the two halves.

No literal secrets, in either file (2026-08-07 security review): both ship inside every production jar (src/main/resources), so a working literal there means one stray SPRING_PROFILES_ACTIVE on a production manifest runs real infrastructure on publicly-known keys — forgeable admin JWTs and decryptable datasource credentials. Every secret is a placeholder resolved from the deployment's own environment, in every posture.

# application-development.yml
datapipelines:
  deployment:
    authoring-enabled: ${DATAPIPELINES_DEPLOYMENT_AUTHORING_ENABLED:true}
  auth:
    cookie-secure: ${DATAPIPELINES_AUTH_COOKIE_SECURE:}

# application-hardened.yml
datapipelines:
  deployment:
    authoring-enabled: ${DATAPIPELINES_DEPLOYMENT_AUTHORING_ENABLED:false}
  auth:
    cookie-secure: ${DATAPIPELINES_AUTH_COOKIE_SECURE:true}

Everything else the posture means is a §7 REFUSAL, which no YAML file can carry: demo, a seeded bootstrap credential, loopback infrastructure and a missing OIDC provider are all refused under hardened. The full table is §3.23.

The laptop's own settings, for reference (DEVELOPMENT.md §2/§4) — ordinary lines in deploy/env/defaults.env, read FIRST like every other default, with no inversion of the secrets-last rule:

DATAPIPELINES_ENV=local
DATAPIPELINES_POSTURE=development
SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5434/datapipelines
SPRING_DATASOURCE_USERNAME=datapipelines
DATAPIPELINES_REDIS_HOST=localhost
DATAPIPELINES_REDIS_PORT=6381
DATAPIPELINES_OBSERVABILITY_LOGGING_FORMAT=console
DATAPIPELINES_AUTH_ALLOWLIST_DOMAINS=

The two passwords are absent on purpose: they are secrets, they live only in deploy/secrets.env, and deploy/compose.laptop-infra.yml starts its Postgres and Redis from those same two variables (each keeping its historical fixed dev value as the interpolation default). Before 081 that file hard-coded datapipelines and no Redis password at all, and a third env file had to be loaded after the secrets to undo them — the one inversion this design used to have. DATAPIPELINES_AUTH_BASE_URL is likewise absent: it is this deployment's own identity and lives in secrets.env, where the scaffold writes http://localhost:<port>.

Dev host ports (2026-08-12): the laptop's Postgres listens on host port 5434 and Redis on 6381 — not the universal defaults 5432/6379, which collide with other local stacks on developer machines (Postgres.app/brew default to 5432). The host mapping lives in deploy/compose.laptop-infra.yml; SPRING_DATASOURCE_URL and DATAPIPELINES_REDIS_PORT in deploy/env/defaults.env must stay in sync with it and with DEVELOPMENT.md §2/§4. In production, SPRING_DATASOURCE_URL and DATAPIPELINES_REDIS_* are operator-set and unaffected.

7. Config Validation

On startup, the app validates:

• All required keys present → fail-fast with a clear error if missing.
• DATAPIPELINES_JWT_SECRET ≥ 32 bytes decoded.
• DATAPIPELINES_DB_ENCRYPTION_KEY is exactly 32 bytes decoded.
• Key provider (§3.20): datapipelines.db.key-provider names a provider this build ships (a violation lists them and points at docs/key-providers.md), and that provider's own settings are present and well-formed. For env: every entry of datapipelines.db.encryption-keys has an integer version in 1..255 that is not 1, and a value that decodes to exactly 32 bytes; datapipelines.db.encryption-key-current is an integer naming a configured version (the violation lists which versions ARE configured). An unknown provider name short-circuits the rest — reporting env's key rules to an operator who asked for aws-kms is noise they cannot act on.
• DATAPIPELINES_UI_THEME matches a vendored theme directory.
• At least one authentication method: a fully-configured OIDC provider (non-empty client-id, client-secret, and issuer-uri) or datapipelines.auth.local.enabled=true. A provider entry with an empty client-id is ignored with a WARN — it does not count, and it is not a violation on its own.
• datapipelines.auth.local.bootstrap-password and datapipelines.auth.local.bootstrap-password-hash are never both set; either seed requires datapipelines.auth.local.enabled=true AND datapipelines.auth.bootstrap-admin-email — each violation names both keys.
• datapipelines.auth.local.lockout.max-failures and datapipelines.auth.local.lockout.duration-minutes are positive integers.
• The deprecated executor alias datapipelines.executor.max-concurrent-executions-global (050/R2): set alone → its value runs and startup logs one WARN naming max-concurrent-executions-per-instance; set together with the new key and differing → startup REFUSES naming both keys.
• result.ttl-min-seconds ≤ result.ttl-default-seconds ≤ result.ttl-max-seconds.
• endpoints.timeout-min-seconds ≤ endpoints.timeout-default-seconds ≤ endpoints.timeout-max-seconds, and the minimum is ≥ 1 (§3.22). Unlike the result TTLs, an ABSENT key is not a violation here — the binder default applies — so only a present, out-of-order triple refuses startup.
• datapipelines.workspaces.provisioning-mode is one of auto-per-user | self-serve | closed.
• datapipelines.workspaces.open-join: true together with closed provisioning is refused, naming both keys (§3.17) — open-join is a self-serve knob, and under closed it would let any authenticated user self-join any workspace, the exact surface closed exists to close.
• Every datapipelines.auth.trusted-proxies entry parses as a CIDR (a bare IP is a host CIDR); anything else refuses startup at the auth module's resolver construction — a typo'd range must not silently widen proxy trust.
• datapipelines.bootstrap.datasources-file is not set without datapipelines.auth.bootstrap-admin-email (§3.18) — the violation names both keys.
• datapipelines.bootstrap.examples-file is not set while datapipelines.workspaces.provisioning-mode is anything but auto-per-user (§3.18) — the violation names both keys. Only auto-per-user provisions the personal workspace the examples are seeded into, so any other mode (the shipped default included) leaves the configured file permanently unseeded. A mode that is misspelled is reported by the mode check alone, not twice.
• No OIDC provider is named bootstrap, local or system. Those are the users.provider values the system writes for identities it creates itself (§6.1 bootstrap actor, §5A local accounts, Auth §4.5 system service account), and a provider's configured name is written to that column verbatim — an external provider under any of them would be indistinguishable from them, and for system that indistinguishability is the whole of the account's safety argument. The reservation is case-insensitive and applies to an entry with a blank client-id too.
• Environment name (§3.23): datapipelines.env matches [a-z0-9][a-z0-9_-]{0,31}. The deprecated datapipelines.deployment.name alias: set alone it still names the deployment and startup logs event=config.deployment_name_deprecated; set together with datapipelines.env and disagreeing, startup is REFUSED naming both keys.
• Posture (§3.23): datapipelines.posture is development or hardened. A named environment with no posture refuses to start, naming both variables — the sole exception is the environment named local, which resolves to development. Explicit beats guessed: the product cannot infer a stance from a name it is forbidden to branch on.
• Posture / profile alignment (§3.23): spring.profiles.active is derived from the posture, so setting SPRING_PROFILES_ACTIVE to a DIFFERENT posture refuses startup naming both — otherwise one posture's defaults would load while every posture rule below judged the other. The dev profile was renamed development in 075; a deployment still asking for dev is refused rather than silently getting no posture file at all.
• The hardened posture (§3.23), each refusal naming the variable and the posture: datapipelines.demo must be empty; no local bootstrap credential may be set (bootstrap-password or bootstrap-password-hash — local accounts themselves stay allowed); spring.datasource.url and datapipelines.redis.host must not be loopback (039's dev-profile guard, inverted and reused — "dev convenience must never touch production infrastructure" is the same fact as "a hardened deployment does not run against a laptop's database"); and at least one OIDC provider must be fully configured unless datapipelines.auth.allow-local-only=true, which is logged as event=config.auth_local_only.
• Organisation (§3.21): datapipelines.org.fiscal-start-date is MM-DD and a day the calendar has — 02-30 and 13-01 are refused, and a month name (SEP-15) is refused with a message naming the MM-DD form; datapipelines.org.week-start is monday or sunday; datapipelines.org.timezone is an IANA zone id (a fixed offset such as +02:00 is not one); datapipelines.org.currency.name and .symbol are non-blank. All four report together — every value is in every Context, so a wrong one is a wrong number in every report the deployment produces.
• Redis auth warning: when datapipelines.redis.password is empty and datapipelines.redis.host is not loopback, log a structured WARN (production Redis holds materialized caller results — Deployment §7.3).
• datapipelines.deployment.promotion.server-key set ⇒ WARN (091): the value is deprecated in favour of a server-kind API key and is removed next release. Presence only — the warning never carries the secret.
• datapipelines.deployment.promotion.target.base-url is not set without datapipelines.deployment.promotion.target.server-key (§3.19) — the violation names both keys. The target's pre-shared key is what authenticates the push, so a target without one would have every promotion refused at the far end, at the end of a UI action a human took. The reverse is not a violation: a server-key with no target is an ordinary receiver.
• Mail (§3.27, 137): datapipelines.mail.host and datapipelines.mail.from are set together or not at all — one without the other refuses startup naming the missing one; datapipelines.mail.ops-to without host is refused (a sink nobody can reach); mail on (both set) without datapipelines.auth.base-url is refused (the welcome mail's login URL); port is a port in 1..65535; from is an address (a bare address or Display Name <address>). Under the hardened posture, with mail on: starttls must be true, and username set requires password set — each refusal naming the variable and the posture. The SMTP password is carried as PRESENCE only; no violation ever prints it.
• The boot line (§3.23): event=config.posture env=<env> posture=<posture> authoring=<on|off> demo=<families> is logged once (the label's only consumer — no code branches on it, pinned by a guard test). When a promotion receiver key is configured AND datapipelines.deployment.authoring-enabled=true, log a structured WARN — a promotion receiver should not author (Versioning D7), though a one-box deployment may legitimately be both. And when authoring is DISABLED while draft pipeline/template versions still exist, startup FAILS naming them: someone authored on a receiver and version alignment may already be broken (Versioning §5.5/§9.3).

The validator's own test suite must assert that the documented laptop setup (deploy/env/defaults.env + deploy/secrets.env, §6) passes the production rules — so a broken local value gets fixed at the data, never by weakening the check.

Validation runs in @PostConstruct of a ConfigValidator bean. Failures stop startup with a clear log message listing every missing/invalid key.

Appendix A: Change Log