feat: harden community production foundation through story 1.5

2026-08-14 00:21:59 +03:00
parent c30461cc92
commit f6fc2e5c9b
161 changed files with 16758 additions and 2515 deletions
@@ -1,46 +1,34 @@
-POSTGRES_DB=crank
-POSTGRES_USER=crank
-POSTGRES_PASSWORD=change-me
+# Deployment-only image and publication settings.
+CRANK_ADMIN_API_IMAGE=crank/admin-api:dev
+CRANK_MCP_SERVER_IMAGE=crank/mcp-server:dev
+CRANK_UI_IMAGE=crank/ui:dev
+CRANK_PUBLISH_BIND=127.0.0.1
+
+# BEGIN GENERATED CRANK RUNTIME CONFIG
+CRANK_DATABASE_URL=
 POSTGRES_HOST=postgres
 POSTGRES_PORT=5432
+POSTGRES_DB=crank
+POSTGRES_USER=crank
+POSTGRES_PASSWORD=
 POSTGRES_MAX_CONNECTIONS=20
 POSTGRES_MIN_CONNECTIONS=2
 POSTGRES_ACQUIRE_TIMEOUT_MS=5000
 POSTGRES_IDLE_TIMEOUT_MS=600000
 POSTGRES_MAX_LIFETIME_MS=1800000
-CRANK_ADMIN_API_IMAGE=crank/admin-api:dev
-CRANK_MCP_SERVER_IMAGE=crank/mcp-server:dev
-CRANK_UI_IMAGE=crank/ui:dev
-CRANK_STORAGE_ROOT=/var/lib/crank/storage
-CRANK_PUBLISH_BIND=127.0.0.1
-CRANK_ADMIN_BIND=0.0.0.0:3001
-CRANK_ADMIN_RATE_LIMIT_RPS=30
-CRANK_ADMIN_RATE_LIMIT_BURST=60
-CRANK_MCP_BIND=0.0.0.0:3002
-CRANK_MCP_REFRESH_MS=5000
-CRANK_MCP_RATE_LIMIT_RPS=60
-CRANK_MCP_RATE_LIMIT_BURST=120
+CRANK_MASTER_KEY=
+CRANK_BASE_URL=http://localhost:3000
 CRANK_RUNTIME_MAX_CONCURRENT_UNARY=64
-CRANK_RUNTIME_MAX_CONCURRENT_WINDOW=16
-CRANK_RUNTIME_MAX_CONCURRENT_SESSIONS=16
-CRANK_RUNTIME_MAX_CONCURRENT_JOBS=16
-# Публичные узлы разрешены по умолчанию. Для внутренних API перечислите
-# допустимые имена или IP через запятую.
+CRANK_CACHE_BACKEND=memory
+CRANK_CACHE_URL=
 CRANK_OUTBOUND_ALLOWED_HOSTS=
 CRANK_OUTBOUND_DENIED_HOSTS=
 CRANK_OUTBOUND_MAX_RESPONSE_BYTES=4194304
 CRANK_ENVIRONMENT=development
-CRANK_LOG_LEVEL=info
-# Пустое значение отключает канал критических ошибок.
+CRANK_LOG_LEVEL=
 CRANK_SENTRY_DSN=
-# Prometheus endpoints use separate listeners and stay on loopback by default.
 CRANK_METRICS_ENABLED=true
-CRANK_ADMIN_METRICS_BIND=127.0.0.1:9464
-CRANK_MCP_METRICS_BIND=127.0.0.1:9465
-# Required when either metrics listener uses a non-loopback address.
 CRANK_METRICS_BEARER_TOKEN=
-CRANK_INVOCATION_LOG_RETENTION_DAYS=30
-# Пустой endpoint полностью отключает экспорт трасс.
 OTEL_EXPORTER_OTLP_ENDPOINT=
 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=
 OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
@@ -53,15 +41,24 @@ OTEL_BSP_MAX_QUEUE_SIZE=2048
 OTEL_BSP_MAX_EXPORT_BATCH_SIZE=512
 OTEL_BSP_SCHEDULE_DELAY=5000
 OTEL_BSP_EXPORT_TIMEOUT=30000
-CRANK_MASTER_KEY=change-me-master-key
-CRANK_SESSION_SECRET=change-me-session-secret
-CRANK_PASSWORD_PEPPER=change-me-password-pepper
+CRANK_ADMIN_BIND=0.0.0.0:3001
+CRANK_ADMIN_METRICS_BIND=127.0.0.1:9464
+CRANK_STORAGE_ROOT=/var/lib/crank/storage
+CRANK_ADMIN_RATE_LIMIT_RPS=30
+CRANK_ADMIN_RATE_LIMIT_BURST=60
+CRANK_INVOCATION_LOG_RETENTION_DAYS=30
+CRANK_SESSION_SECRET=
+CRANK_PASSWORD_PEPPER=
 CRANK_SESSION_TTL_HOURS=24
-# Trust X-Real-IP / X-Forwarded-For for client rate limiting. Enable only when
-# admin-api runs behind the bundled nginx (or another trusted reverse proxy).
-CRANK_TRUST_FORWARDED_HEADERS=true
-CRANK_BOOTSTRAP_ADMIN_EMAIL=owner@crank.local
-CRANK_BOOTSTRAP_ADMIN_PASSWORD=change-me-admin-password
+CRANK_TRUST_FORWARDED_HEADERS=false
+CRANK_BOOTSTRAP_ADMIN_EMAIL=
+CRANK_BOOTSTRAP_ADMIN_PASSWORD=
 CRANK_BOOTSTRAP_ADMIN_DISPLAY_NAME=Crank Owner
-CRANK_DEMO_SEED=true
-CRANK_BASE_URL=https://crank.example.com
+CRANK_DEMO_SEED=false
+CRANK_MCP_BIND=0.0.0.0:3002
+CRANK_MCP_METRICS_BIND=127.0.0.1:9465
+CRANK_MCP_REFRESH_MS=5000
+CRANK_MCP_RATE_LIMIT_RPS=60
+CRANK_MCP_RATE_LIMIT_BURST=120
+CRANK_RUNTIME_MAX_CONCURRENT_SESSIONS=16
+# END GENERATED CRANK RUNTIME CONFIG
@@ -61,6 +61,34 @@ jobs:
      - name: Run tooling unit tests
        run: python3 -m unittest discover -s tests/unit

+      - name: Check typed runtime configuration contract
+        run: |
+          cargo run -p crank-config --bin crank-config-contract -- --check
+          python3 scripts/check-runtime-config.py --root .
+          python3 scripts/check-config-boundaries.py --root .
+
+      - name: Check canonical migration contract
+        run: cargo run -p admin-api --bin crank-migrate -- plan --check
+
+      - name: Check Capability Inventory
+        run: |
+          required_args=""
+          for number in $(seq 1 54); do
+            required_args="$required_args --required-fr FR-$number"
+          done
+          python3 scripts/validate-capability-inventory.py \
+            --root . \
+            --inventory docs/capability-inventory.json \
+            --schema docs/schemas/capability-inventory.schema.json \
+            $required_args
+
+      - name: Check Capability Baseline
+        run: |
+          python3 scripts/validate-capability-baseline.py \
+            --root . \
+            --manifest docs/capability-baseline/manifest.json \
+            --schema docs/schemas/capability-baseline.schema.json
+
      - name: Check Community scope
        run: scripts/check-community-scope.sh

@@ -80,7 +108,7 @@ jobs:
        run: cargo clippy --workspace --all-targets --all-features --jobs "$CARGO_BUILD_JOBS" -- -D warnings

      - name: Run tests
-        run: cargo test --workspace --all-targets --jobs "$CARGO_BUILD_JOBS"
+        run: cargo test --workspace --all-targets --jobs "$CARGO_BUILD_JOBS" -- --test-threads=1

  ui:
    name: UI Checks
@@ -199,8 +227,11 @@ jobs:
      - name: Checkout
        uses: actions/checkout@v5

-      - name: Validate Community deployment manifest
-        run: docker compose -f deploy/community/docker-compose.yml --env-file deploy/community/.env.example config -q
+      - name: Validate Community deployment manifests
+        run: |
+          docker compose -f docker-compose.yml --env-file .env.example config -q
+          docker compose -f deploy/community/docker-compose.yml --env-file deploy/community/.env.example config -q
+          docker compose -f deploy/community/docker-compose.images.yml --env-file deploy/community/.env.images.example --profile local-db config -q

      - name: Build Community images
        run: |
@@ -41,6 +41,7 @@ jobs:

      - name: Verify runner toolchain
        run: |
+          python3 --version
          rustc --version
          cargo --version
          node --version
@@ -52,11 +53,46 @@ jobs:
      - name: Install dependency policy tool
        run: cargo install cargo-deny --version 0.20.2 --locked

+      - name: Run tooling unit tests
+        run: python3 -m unittest discover -s tests/unit
+
+      - name: Check typed runtime configuration contract
+        run: |
+          cargo run -p crank-config --bin crank-config-contract -- --check
+          python3 scripts/check-runtime-config.py --root .
+          python3 scripts/check-config-boundaries.py --root .
+          scripts/check-rust-boundaries.sh
+
+      - name: Check canonical migration contract
+        run: cargo run -p admin-api --bin crank-migrate -- plan --check
+
+      - name: Check Capability Inventory
+        run: |
+          required_args=""
+          for number in $(seq 1 54); do
+            required_args="$required_args --required-fr FR-$number"
+          done
+          python3 scripts/validate-capability-inventory.py \
+            --root . \
+            --inventory docs/capability-inventory.json \
+            --schema docs/schemas/capability-inventory.schema.json \
+            $required_args
+
+      - name: Check Capability Baseline
+        run: |
+          python3 scripts/validate-capability-baseline.py \
+            --root . \
+            --manifest docs/capability-baseline/manifest.json \
+            --schema docs/schemas/capability-baseline.schema.json
+
+      - name: Check Community scope
+        run: scripts/check-community-scope.sh
+
      - name: Run release quality gates
        run: |
          cargo fmt --all --check
          cargo clippy --workspace --all-targets --all-features -- -D warnings
-          cargo test --workspace --all-targets
+          cargo test --workspace --all-targets -- --test-threads=1
          cargo deny --locked check advisories bans licenses sources

      - name: Build release binaries
@@ -82,15 +118,19 @@ jobs:
        working-directory: apps/ui
        run: npm run e2e

-      - name: Validate deployment manifest
-        run: docker compose -f deploy/community/docker-compose.yml --env-file deploy/community/.env.example config -q
+      - name: Validate deployment manifests
+        run: |
+          docker compose -f docker-compose.yml --env-file .env.example config -q
+          docker compose -f deploy/community/docker-compose.yml --env-file deploy/community/.env.example config -q
+          docker compose -f deploy/community/docker-compose.images.yml --env-file deploy/community/.env.images.example --profile local-db config -q

      - name: Package release artifacts
        run: |
          mkdir -p dist/release
          cp target/release/admin-api dist/release/admin-api
+          cp target/release/crank-migrate dist/release/crank-migrate
          cp target/release/mcp-server dist/release/mcp-server
-          tar -C dist/release -czf dist/crank-community-admin-api-${IMAGE_TAG}.tar.gz admin-api
+          tar -C dist/release -czf dist/crank-community-admin-api-${IMAGE_TAG}.tar.gz admin-api crank-migrate
          tar -C dist/release -czf dist/crank-community-mcp-server-${IMAGE_TAG}.tar.gz mcp-server
          tar -C apps/ui/dist -czf dist/crank-community-ui-${IMAGE_TAG}.tar.gz .
          sha256sum \
@@ -130,6 +170,32 @@ jobs:
          docker build -f apps/ui/Dockerfile \
            -t '${{ env.UI_IMAGE }}:${{ env.IMAGE_TAG }}' \
            -t '${{ env.UI_IMAGE }}:latest' .
+          mkdir -p .tmp
+          cat > .tmp/release-migration-smoke.env <<EOF
+          COMPOSE_PROJECT_NAME=crank-release-migration-${{ github.run_id }}-${{ github.run_attempt }}
+          POSTGRES_HOST=postgres
+          POSTGRES_DB=crank
+          POSTGRES_USER=crank
+          POSTGRES_PASSWORD=release-smoke-password
+          CRANK_ADMIN_API_IMAGE=${{ env.ADMIN_API_IMAGE }}:${{ env.IMAGE_TAG }}
+          CRANK_MCP_SERVER_IMAGE=${{ env.MCP_SERVER_IMAGE }}:${{ env.IMAGE_TAG }}
+          CRANK_UI_IMAGE=${{ env.UI_IMAGE }}:${{ env.IMAGE_TAG }}
+          CRANK_MASTER_KEY=0000000000000000000000000000000000000000000000000000000000000000
+          CRANK_SESSION_SECRET=release-smoke-session
+          CRANK_PASSWORD_PEPPER=release-smoke-pepper
+          CRANK_BOOTSTRAP_ADMIN_EMAIL=owner@crank.test
+          CRANK_BOOTSTRAP_ADMIN_PASSWORD=release-smoke-password
+          CRANK_BASE_URL=http://127.0.0.1
+          CRANK_PUBLISH_BIND=127.0.0.1
+          CRANK_ADMIN_PUBLISH_PORT=0
+          CRANK_MCP_PUBLISH_PORT=0
+          CRANK_UI_PUBLISH_PORT=0
+          EOF
+          trap 'docker compose -f deploy/community/docker-compose.images.yml --env-file .tmp/release-migration-smoke.env --profile local-db down -v --remove-orphans || true' EXIT
+          docker compose -f deploy/community/docker-compose.images.yml \
+            --env-file .tmp/release-migration-smoke.env --profile local-db up -d --wait
+          docker compose -f deploy/community/docker-compose.images.yml \
+            --env-file .tmp/release-migration-smoke.env --profile local-db logs migrate | grep '"status":"applied"'
          scripts/scan-images.sh \
            '${{ env.ADMIN_API_IMAGE }}:${{ env.IMAGE_TAG }}' \
            '${{ env.MCP_SERVER_IMAGE }}:${{ env.IMAGE_TAG }}' \
@@ -23,3 +23,6 @@ __*.md
 diploma/
 AGENTS.md
 TASKS.md
+
+# BMAD workspace data and generated artifacts
+**/_bmad*/
@@ -30,10 +30,25 @@ npx playwright test
 ## Требования к изменениям

 - Не добавляйте функциональность вне границ Community-версии.
+- Сверяйте границу и статус flow с
+  [`docs/capability-inventory.json`](./docs/capability-inventory.json): только
+  `implemented` считается готовым, а `planned`, `gap` и `blocked` не являются
+  разрешением заявить незавершённую функцию работающей.
+- Если change меняет capability status или evidence, обновите versioned
+  [`docs/capability-baseline/manifest.json`](./docs/capability-baseline/manifest.json),
+  sanitized results и SHA-256. Нельзя вручную объявлять pass для failed, flaky,
+  skipped, not-run или manual-only evidence.
 - Не добавляйте секреты, токены, приватные адреса и локальные настройки.
 - Не коммитьте `AGENTS.md`, `TASKS.md`, `.env` и временные файлы.
 - Для изменений SQL-запросов обновляйте `.sqlx`, если это требуется SQLx.
+- Изменение PostgreSQL schema начинается с новой append-only migration в
+  `crank-registry`; baseline v1 не редактируется. Выполните
+  `just migration-contract-check` и PostgreSQL migration integration suite.
 - Для пользовательских изменений обновляйте документацию или примеры.
+- Runtime environment contract изменяется только через registry
+  `crates/crank-config`. После изменения выполните
+  `just config-contract-check`; generated sections `.env.example`, Compose и
+  parameter reference не поддерживаются независимыми ручными таблицами.

 ## Границы проекта

@@ -47,3 +62,5 @@ npx playwright test
 - необязательный Valkey или Redis для служебного кэша.

 Функции за пределами перечисленного набора не должны попадать в этот репозиторий.
+Целевые Resources, Prompts, Tasks и Load Runs допускаются только через
+проверяемое изменение Inventory, guardrails, tests и документации.
@@ -27,6 +27,7 @@ dependencies = [
 "axum-extra",
 "base64",
 "crank-community-auth",
+ "crank-config",
 "crank-core",
 "crank-import",
 "crank-mapping",
@@ -576,15 +577,6 @@ dependencies = [
 "tokio-util",
 ]

-[[package]]
-name = "concurrent-queue"
-version = "2.5.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4ca0197aee26d1ae37445ee532fefce43251d24cc7c166799f4d46817f1d3973"
-dependencies = [
- "crossbeam-utils",
-]
-
 [[package]]
 name = "cookie"
 version = "0.18.1"
@@ -723,6 +715,16 @@ dependencies = [
 "uuid",
 ]

+[[package]]
+name = "crank-config"
+version = "0.3.1"
+dependencies = [
+ "serde",
+ "serde_json",
+ "sha2 0.10.9",
+ "url",
+]
+
 [[package]]
 name = "crank-core"
 version = "0.3.1"
@@ -734,6 +736,7 @@ dependencies = [
 "thiserror 2.0.18",
 "time",
 "tokio",
+ "uuid",
 ]

 [[package]]
@@ -795,7 +798,6 @@ dependencies = [
 "tracing-opentelemetry",
 "tracing-subscriber",
 "url",
- "uuid",
 ]

 [[package]]
@@ -874,7 +876,10 @@ dependencies = [
 name = "crank-trace"
 version = "0.3.1"
 dependencies = [
+ "crank-core",
+ "opentelemetry",
 "tracing",
+ "tracing-opentelemetry",
 "tracing-subscriber",
 ]

@@ -1122,11 +1127,10 @@ dependencies = [

 [[package]]
 name = "event-listener"
-version = "5.4.1"
+version = "5.4.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e13b66accf52311f30a0db42147dadea9850cb48cd070028831ae5f5d4b856ab"
+checksum = "5a23add41df1562121a9393cb065eab5146a1242410f23a644851e90cfd669d2"
 dependencies = [
- "concurrent-queue",
 "parking",
 "pin-project-lite",
 ]
@@ -2019,6 +2023,7 @@ dependencies = [
 "axum",
 "base64",
 "crank-community-mcp",
+ "crank-config",
 "crank-core",
 "crank-mapping",
 "crank-observability",
@@ -4,6 +4,7 @@ members = [
    "apps/mcp-server",
    "crates/crank-community-auth",
    "crates/crank-community-mcp",
+    "crates/crank-config",
    "crates/crank-core",
    "crates/crank-import",
    "crates/crank-schema",
@@ -165,6 +165,20 @@ docker compose up -d --build
 - PostgreSQL как основное хранилище;
 - необязательный Valkey или Redis для служебного кэша.

+Текущие и целевые возможности фиксируются в
+[`docs/capability-inventory.json`](docs/capability-inventory.json). Статус
+`implemented` означает реализованный flow; `planned`, `gap` и `blocked` не
+считаются готовностью. MCP Resources, Prompts, фоновые Tasks и встроенные Load
+Runs сейчас перечислены только как planned target и не выдаются за работающие
+возможности этой версии.
+
+Проверенный snapshot текущих UI, Admin API и MCP flows находится в
+[`docs/capability-baseline/manifest.json`](docs/capability-baseline/manifest.json).
+Он связывает inventory, обязательные surfaces, taxonomy, manual checklist и
+sanitized results точными SHA-256. Полный baseline pass требует сочетания
+`implemented + automated + pass`; skipped, flaky, not-run и manual-only не
+становятся pass.
+
 ## Структура проекта

 ```text
@@ -268,7 +282,10 @@ npx playwright test
 - [Production checklist](docs/production-checklist.md)
 - [Troubleshooting](docs/troubleshooting.md)
 - [Настройки запуска](docs/runtime-config.md)
+- [Machine schema runtime-конфигурации](docs/schemas/runtime-config.schema.json)
 - [Английский README](docs/en/README.md)
+- [Capability Inventory](docs/capability-inventory.json)
+- [Capability Baseline](docs/capability-baseline/manifest.json)

 ## Участие в разработке

@@ -10,12 +10,17 @@ version.workspace = true
 name = "admin-api"
 path = "src/main.rs"

+[[bin]]
+name = "crank-migrate"
+path = "src/bin/crank-migrate.rs"
+
 [dependencies]
 argon2.workspace = true
 axum.workspace = true
 axum-extra.workspace = true
 base64.workspace = true
 crank-community-auth = { path = "../../crates/crank-community-auth" }
+crank-config = { path = "../../crates/crank-config" }
 crank-core = { path = "../../crates/crank-core" }
 crank-import = { path = "../../crates/crank-import" }
 crank-mapping = { path = "../../crates/crank-mapping" }
@@ -1,41 +1,3 @@
-FROM rust:1.96.1-bookworm AS deps
-
-WORKDIR /app
-
-COPY Cargo.toml Cargo.lock ./
-COPY .sqlx ./.sqlx
-COPY apps/admin-api/Cargo.toml apps/admin-api/Cargo.toml
-COPY apps/mcp-server/Cargo.toml apps/mcp-server/Cargo.toml
-COPY crates/crank-core/Cargo.toml crates/crank-core/Cargo.toml
-COPY crates/crank-schema/Cargo.toml crates/crank-schema/Cargo.toml
-COPY crates/crank-mapping/Cargo.toml crates/crank-mapping/Cargo.toml
-COPY crates/crank-registry/Cargo.toml crates/crank-registry/Cargo.toml
-COPY crates/crank-runtime/Cargo.toml crates/crank-runtime/Cargo.toml
-COPY crates/crank-adapter-rest/Cargo.toml crates/crank-adapter-rest/Cargo.toml
-
-RUN mkdir -p \
-    apps/admin-api/src \
-    apps/mcp-server/src \
-    crates/crank-core/src \
-    crates/crank-schema/src \
-    crates/crank-mapping/src \
-    crates/crank-registry/src \
-    crates/crank-runtime/src \
-    crates/crank-adapter-rest/src \
-    && printf 'fn main() {}\n' > apps/admin-api/src/main.rs \
-    && printf 'fn main() {}\n' > apps/mcp-server/src/main.rs \
-    && printf 'pub fn placeholder() {}\n' > crates/crank-core/src/lib.rs \
-    && printf 'pub fn placeholder() {}\n' > crates/crank-schema/src/lib.rs \
-    && printf 'pub fn placeholder() {}\n' > crates/crank-mapping/src/lib.rs \
-    && printf 'pub fn placeholder() {}\n' > crates/crank-registry/src/lib.rs \
-    && printf 'pub fn placeholder() {}\n' > crates/crank-runtime/src/lib.rs \
-    && printf 'pub fn placeholder() {}\n' > crates/crank-adapter-rest/src/lib.rs
-
-RUN --mount=type=cache,target=/usr/local/cargo/registry \
-    --mount=type=cache,target=/usr/local/cargo/git/db \
-    --mount=type=cache,target=/app/target \
-    SQLX_OFFLINE=true cargo build --release -p admin-api
-
 FROM rust:1.96.1-bookworm AS builder

 WORKDIR /app
@@ -45,11 +7,12 @@ COPY .sqlx ./.sqlx
 COPY apps ./apps
 COPY crates ./crates

-RUN --mount=type=cache,target=/usr/local/cargo/registry \
-    --mount=type=cache,target=/usr/local/cargo/git/db \
-    --mount=type=cache,target=/app/target \
+RUN --mount=type=cache,id=crank-admin-cargo-registry,target=/usr/local/cargo/registry \
+    --mount=type=cache,id=crank-admin-cargo-git,target=/usr/local/cargo/git/db \
+    --mount=type=cache,id=crank-admin-target,target=/app/target \
    SQLX_OFFLINE=true cargo build --release -p admin-api \
-    && cp /app/target/release/admin-api /tmp/admin-api
+    && cp /app/target/release/admin-api /tmp/admin-api \
+    && cp /app/target/release/crank-migrate /tmp/crank-migrate

 FROM debian:bookworm-slim

@@ -60,6 +23,7 @@ RUN apt-get update \
 WORKDIR /app

 COPY --from=builder /tmp/admin-api /usr/local/bin/admin-api
+COPY --from=builder /tmp/crank-migrate /usr/local/bin/crank-migrate

 ENV CRANK_ADMIN_BIND=0.0.0.0:3001

@@ -0,0 +1,242 @@
+use std::{process::ExitCode, time::Duration};
+
+use crank_config::{ConfigSource, DatabaseSettings, parse_migrator};
+use crank_registry::{
+    BackfillPolicy, MigrationApplyResult, MigrationAuthority, MigrationPreflight,
+};
+use serde_json::json;
+use sqlx::{
+    PgPool,
+    postgres::{PgConnectOptions, PgPoolOptions},
+};
+
+#[tokio::main]
+async fn main() -> ExitCode {
+    match run().await {
+        Ok(code) => code,
+        Err(error) => {
+            eprintln!(
+                "{}",
+                json!({
+                    "status": "error",
+                    "code": error.code,
+                    "stage": error.stage,
+                    "version": error.version,
+                    "recovery": error.recovery,
+                })
+            );
+            ExitCode::FAILURE
+        }
+    }
+}
+
+#[derive(Clone, Copy)]
+struct CliError {
+    code: &'static str,
+    stage: &'static str,
+    recovery: &'static str,
+    version: Option<i64>,
+}
+
+impl CliError {
+    const fn new(code: &'static str, stage: &'static str, recovery: &'static str) -> Self {
+        Self {
+            code,
+            stage,
+            recovery,
+            version: None,
+        }
+    }
+
+    fn from_migration(error: crank_registry::MigrationError) -> Self {
+        Self {
+            code: error.code(),
+            stage: error.stage(),
+            recovery: error.recovery(),
+            version: error.version(),
+        }
+    }
+}
+
+async fn run() -> Result<ExitCode, CliError> {
+    let mut arguments = std::env::args().skip(1);
+    let requested = arguments.next();
+    let option = arguments.next();
+    if arguments.next().is_some() {
+        return Err(CliError::new(
+            "invalid_command",
+            "cli.arguments",
+            "run_preflight",
+        ));
+    }
+    let command = match requested.as_deref() {
+        None | Some("preflight") => "preflight",
+        Some("plan") => "plan",
+        Some("apply") => "apply",
+        Some(_) => {
+            return Err(CliError::new(
+                "invalid_command",
+                "cli.arguments",
+                "run_preflight",
+            ));
+        }
+    };
+
+    if command == "plan" {
+        MigrationAuthority::validate_sequence().map_err(CliError::from_migration)?;
+        let sequence = MigrationAuthority::sequence()
+            .into_iter()
+            .map(|migration| {
+                let backfill = match migration.backfill {
+                    BackfillPolicy::None => json!({ "kind": "none" }),
+                    BackfillPolicy::Bounded {
+                        max_batch_rows,
+                        max_batch_ms,
+                        resumable,
+                    } => json!({
+                        "kind": "bounded",
+                        "max_batch_rows": max_batch_rows,
+                        "max_batch_ms": max_batch_ms,
+                        "resumable": resumable,
+                    }),
+                };
+                json!({
+                    "version": migration.version,
+                    "name": migration.name,
+                    "checksum": migration.checksum,
+                    "source_digest": migration.source_digest,
+                    "phase": migration.phase,
+                    "compatibility": migration.compatibility,
+                    "owner": migration.owner,
+                    "transactional": migration.transactional,
+                    "backfill": backfill,
+                    "readable_schema_min": migration.readable_schema_min,
+                    "readable_schema_max": migration.readable_schema_max,
+                    "contract_evidence": migration.contract_evidence,
+                })
+            })
+            .collect::<Vec<_>>();
+        let plan = json!({ "schema_version": 1, "sequence": sequence });
+        if option.as_deref() == Some("--check") {
+            let bytes = std::fs::read("docs/schemas/migration-sequence.json")
+                .map_err(|_| CliError::new("contract_drift", "plan.read", "contact_operator"))?;
+            if bytes.len() > 65_536 {
+                return Err(CliError::new(
+                    "contract_drift",
+                    "plan.size",
+                    "contact_operator",
+                ));
+            }
+            let committed: serde_json::Value = serde_json::from_slice(&bytes)
+                .map_err(|_| CliError::new("contract_drift", "plan.parse", "contact_operator"))?;
+            if committed != plan {
+                return Err(CliError::new(
+                    "contract_drift",
+                    "plan.compare",
+                    "contact_operator",
+                ));
+            }
+            println!("{}", json!({ "status": "contract_current" }));
+            return Ok(ExitCode::SUCCESS);
+        }
+        if option.is_some() {
+            return Err(CliError::new(
+                "invalid_command",
+                "cli.arguments",
+                "run_preflight",
+            ));
+        }
+        println!("{plan}");
+        return Ok(ExitCode::SUCCESS);
+    }
+    if option.is_some() {
+        return Err(CliError::new(
+            "invalid_command",
+            "cli.arguments",
+            "run_preflight",
+        ));
+    }
+
+    let config = parse_migrator(
+        ConfigSource::from_os_for_migrator()
+            .map_err(|_| CliError::new("config_invalid", "config.source", "run_preflight"))?,
+    )
+    .map_err(|_| CliError::new("config_invalid", "config.validate", "run_preflight"))?;
+    let pool = connect(&config.database).await?;
+
+    if command == "apply" {
+        let result = MigrationAuthority::apply(&pool)
+            .await
+            .map_err(CliError::from_migration)?;
+        let (status, from, to) = match result {
+            MigrationApplyResult::Applied { from, to } => ("applied", from, to),
+            MigrationApplyResult::AlreadyCurrent { version } => {
+                ("already_current", version, version)
+            }
+        };
+        println!(
+            "{}",
+            json!({ "status": status, "from_version": from, "to_version": to })
+        );
+        return Ok(ExitCode::SUCCESS);
+    }
+
+    match MigrationAuthority::preflight(&pool)
+        .await
+        .map_err(CliError::from_migration)?
+    {
+        MigrationPreflight::Current { version } => {
+            println!("{}", json!({ "status": "current", "version": version }));
+            Ok(ExitCode::SUCCESS)
+        }
+        MigrationPreflight::MigrationRequired { current, target } => {
+            println!(
+                "{}",
+                json!({
+                    "status": "migration_required",
+                    "current_version": current,
+                    "target_version": target,
+                    "recovery": "run_controlled_migration",
+                })
+            );
+            Ok(ExitCode::from(2))
+        }
+    }
+}
+
+async fn connect(config: &DatabaseSettings) -> Result<PgPool, CliError> {
+    let options = if let Some(url) = &config.url {
+        url.expose_secret()
+            .parse::<PgConnectOptions>()
+            .map_err(|_| CliError::new("config_invalid", "database.source", "run_preflight"))?
+    } else {
+        PgConnectOptions::new()
+            .host(&config.host)
+            .port(config.port)
+            .database(&config.database)
+            .username(&config.username)
+            .password(config.password.expose_secret())
+    };
+    for attempt in 1..=10 {
+        let result = PgPoolOptions::new()
+            .max_connections(config.pool.max_connections)
+            .min_connections(config.pool.min_connections)
+            .acquire_timeout(Duration::from_millis(config.pool.acquire_timeout_ms))
+            .idle_timeout(Duration::from_millis(config.pool.idle_timeout_ms))
+            .max_lifetime(Duration::from_millis(config.pool.max_lifetime_ms))
+            .connect_with(options.clone())
+            .await;
+        match result {
+            Ok(pool) => return Ok(pool),
+            Err(_) if attempt < 10 => {
+                tokio::time::sleep(Duration::from_secs(1)).await;
+            }
+            Err(_) => break,
+        }
+    }
+    Err(CliError::new(
+        "storage_unavailable",
+        "database.connect",
+        "contact_operator",
+    ))
+}
@@ -551,6 +551,7 @@ pub(crate) struct InvocationRecordRequest<'a> {
    pub agent_id: Option<&'a AgentId>,
    pub operation: &'a RegistryOperation,
    pub request_id: Option<&'a str>,
+    pub trace_id: Option<&'a str>,
    pub source: InvocationSource,
    pub level: InvocationLevel,
    pub status: InvocationStatus,
@@ -74,9 +74,9 @@ impl ApiError {
        }
    }

-    pub fn internal(message: impl Into<String>) -> Self {
+    pub fn internal(_message: impl Into<String>) -> Self {
        Self::Internal {
-            message: message.into(),
+            message: "internal server error".to_owned(),
            context: None,
        }
    }
@@ -165,6 +165,13 @@ impl IntoResponse for ApiError {
        if let Some(context) = self.context() {
            error["context"] = context;
        }
+        let (request_id, trace_id) = crank_observability::current_request_correlation();
+        if let Some(request_id) = request_id {
+            error["request_id"] = Value::String(request_id);
+        }
+        if let Some(trace_id) = trace_id {
+            error["trace_id"] = Value::String(trace_id);
+        }

        let body = Json(json!({
            "error": error
@@ -363,9 +370,10 @@ impl From<RegistryError> for ApiError {
                format!("import job {job_id} was already applied with different parameters"),
                json!({ "job_id": job_id }),
            ),
-            RegistryError::Storage(_) | RegistryError::Serialization(_) => {
-                Self::internal(value.to_string())
-            }
+            RegistryError::Migration(_)
+            | RegistryError::Storage(_)
+            | RegistryError::Serialization(_)
+            | RegistryError::InvalidCorrelationIdentity { .. } => Self::internal(value.to_string()),
        }
    }
 }
@@ -399,7 +407,7 @@ impl From<StorageError> for ApiError {
 pub fn runtime_test_failure(error: &RuntimeError) -> Value {
    let mut payload = json!({
        "code": runtime_test_failure_code(error),
-        "message": error.to_string()
+        "message": safe_runtime_test_failure_message(error)
    });
    if let Some(context) = runtime_error_context(error) {
        payload["context"] = context;
@@ -407,6 +415,33 @@ pub fn runtime_test_failure(error: &RuntimeError) -> Value {
    payload
 }

+fn safe_runtime_test_failure_message(error: &RuntimeError) -> &'static str {
+    match error {
+        RuntimeError::Schema(_) => "input schema validation failed",
+        RuntimeError::Mapping(_) => "input mapping failed",
+        RuntimeError::RestAdapter(_) | RuntimeError::ProtocolAdapter(_) => {
+            "upstream execution failed"
+        }
+        RuntimeError::UnsupportedProtocol { .. } => "operation protocol is unsupported",
+        RuntimeError::ConcurrencyLimitExceeded { .. } => "runtime concurrency limit exceeded",
+        RuntimeError::InvalidPreparedRequest { .. } => "prepared request is invalid",
+        RuntimeError::ConfirmationRequired { .. } => "operation confirmation is required",
+        RuntimeError::InvalidConfirmationToken { .. } => "confirmation token is invalid",
+        RuntimeError::ConfirmationStoreUnavailable { .. } => "confirmation store is unavailable",
+        RuntimeError::IdempotencyStoreUnavailable { .. } => "idempotency store is unavailable",
+        RuntimeError::IdempotencyInProgress { .. } => "idempotent execution is in progress",
+        RuntimeError::IdempotencyConflict { .. } => "idempotency key conflicts with the request",
+        RuntimeError::IdempotencyOutcomeUnknown { .. } => "previous execution outcome is unknown",
+        RuntimeError::UnsupportedExecutionMode { .. } => "execution mode is unsupported",
+        RuntimeError::MissingAuthProfile { .. } => "authorization profile is missing",
+        RuntimeError::MissingSecret { .. } | RuntimeError::MissingSecretVersion { .. } => {
+            "authorization secret is missing"
+        }
+        RuntimeError::InvalidAuthSecretValue { .. } => "authorization secret is invalid",
+        RuntimeError::SecretCrypto { .. } => "authorization secret processing failed",
+    }
+}
+
 fn runtime_test_failure_code(error: &RuntimeError) -> &'static str {
    match error {
        RuntimeError::Schema(_) => "runtime_schema_error",
@@ -435,9 +470,8 @@ fn runtime_test_failure_code(error: &RuntimeError) -> &'static str {

 pub fn runtime_error_context(error: &RuntimeError) -> Option<Value> {
    match error {
-        RuntimeError::InvalidPreparedRequest { field, reason } => Some(json!({
+        RuntimeError::InvalidPreparedRequest { field, .. } => Some(json!({
            "field": field,
-            "reason": reason,
        })),
        RuntimeError::ConfirmationRequired {
            confirmation_token,
@@ -457,14 +491,10 @@ pub fn runtime_error_context(error: &RuntimeError) -> Option<Value> {
        | RuntimeError::IdempotencyOutcomeUnknown { operation_id } => Some(json!({
            "operation_id": operation_id,
        })),
-        RuntimeError::InvalidAuthSecretValue { secret_id, reason } => Some(json!({
+        RuntimeError::InvalidAuthSecretValue { secret_id, .. } => Some(json!({
            "secret_id": secret_id,
-            "reason": reason,
-        })),
-        RuntimeError::SecretCrypto { operation, details } => Some(json!({
-            "operation": operation,
-            "details": details,
        })),
+        RuntimeError::SecretCrypto { .. } => None,
        RuntimeError::MissingAuthProfile { auth_profile_id } => Some(json!({
            "auth_profile_id": auth_profile_id,
        })),
@@ -1,4 +1,4 @@
-use std::{env, net::SocketAddr, path::PathBuf, time::Duration};
+use std::{io, net::SocketAddr, process::ExitCode, time::Duration};

 use admin_api::{
    app::build_app,
@@ -8,9 +8,14 @@ use admin_api::{
    state::AppState,
 };
 use crank_community_auth::PasswordIdentityProvider;
+use crank_config::{
+    AdminProcessConfig, CacheBackend as ConfigCacheBackend, ConfigSource, DatabaseSettings,
+    DiagnosticCode, ObservabilitySettings, ProcessKind, parse_process,
+};
+use crank_core::CacheBackend;
 use crank_observability::{
    CriticalErrorCategory, MetricsConfig, ObservabilityConfig, ObservabilityLifecycle,
-    capture_critical_error,
+    OtlpTraceConfig, RedactionLimits, SentryConfig, ServiceIdentity, capture_critical_error,
 };
 use crank_registry::{PostgresPoolConfig, PostgresRegistry};
 use crank_runtime::{
@@ -21,17 +26,77 @@ use sqlx::postgres::PgConnectOptions;
 use tokio::net::TcpListener;
 use tracing::{info, warn};

-const MAX_INVOCATION_LOG_RETENTION_DAYS: i64 = 36_500;
-
 #[tokio::main]
-async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let observability = crank_observability::init(ObservabilityConfig::from_env(
-        "admin-api",
-        env!("CARGO_PKG_VERSION"),
-        "admin_api=info,tower_http=info",
-    )?)?;
+async fn main() -> ExitCode {
+    match main_result().await {
+        Ok(()) => ExitCode::SUCCESS,
+        Err(error) => {
+            eprintln!("{}", safe_startup_diagnostic(error.as_ref()));
+            ExitCode::FAILURE
+        }
+    }
+}
+
+fn safe_startup_diagnostic(error: &(dyn std::error::Error + 'static)) -> String {
+    let mut current = Some(error);
+    while let Some(cause) = current {
+        if let Some(config) = cause.downcast_ref::<crank_config::ConfigError>() {
+            return config.to_json();
+        }
+        if let Some(migration) = cause.downcast_ref::<crank_registry::MigrationError>() {
+            return serde_json::json!({
+                "status": "error",
+                "code": migration.code(),
+                "stage": migration.stage(),
+                "version": migration.version(),
+                "recovery": migration.recovery(),
+            })
+            .to_string();
+        }
+        if let Some(crank_registry::RegistryError::Migration(migration)) =
+            cause.downcast_ref::<crank_registry::RegistryError>()
+        {
+            return serde_json::json!({
+                "status": "error",
+                "code": migration.code(),
+                "stage": migration.stage(),
+                "version": migration.version(),
+                "recovery": migration.recovery(),
+            })
+            .to_string();
+        }
+        current = cause.source();
+    }
+    serde_json::json!({
+        "status": "error",
+        "code": "startup_failed",
+        "stage": "startup",
+        "version": null,
+        "recovery": "contact_operator",
+    })
+    .to_string()
+}
+
+async fn main_result() -> Result<(), Box<dyn std::error::Error>> {
+    let effective = parse_process(ProcessKind::AdminApi, ConfigSource::from_os()?)?;
+    let config = effective
+        .admin()
+        .cloned()
+        .ok_or_else(|| io::Error::other("admin configuration projection is unavailable"))?;
+    preflight_config(&config)?;
+    let observability = init_observability(&config.observability)?;
+    for deprecation in effective.deprecations() {
+        warn!(
+            name: "config.deprecated",
+            field = deprecation.field,
+            source_class = deprecation.source_class,
+            replacement = deprecation.replacement,
+            removal_window = deprecation.removal_window,
+            "deprecated configuration accepted"
+        );
+    }
    let mut startup_completed = false;
-    let result = run(&observability, &mut startup_completed).await;
+    let result = run(config, &observability, &mut startup_completed).await;
    if result.is_err() {
        capture_critical_error(if startup_completed {
            CriticalErrorCategory::Internal
@@ -43,54 +108,67 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 }

 async fn run(
+    config: AdminProcessConfig,
    observability: &ObservabilityLifecycle,
    startup_completed: &mut bool,
 ) -> Result<(), Box<dyn std::error::Error>> {
-    let metrics_config =
-        MetricsConfig::from_env("CRANK_ADMIN_METRICS_BIND", "127.0.0.1:9464".parse()?)?;
+    let metrics_config = MetricsConfig::new(
+        config.observability.metrics.enabled,
+        config.observability.metrics.bind_addr,
+        config
+            .observability
+            .metrics
+            .bearer_token
+            .as_ref()
+            .map(|token| token.expose_secret().to_owned()),
+    )?;
    let metrics_enabled = metrics_config.enabled();
-    let metrics_server = if metrics_config.enabled() {
+    let pool_config = postgres_pool_config(&config.database)?;
+    let registry = PostgresRegistry::connect_with_options_and_pool_config(
+        database_options(&config.database)?,
+        pool_config,
+    )
+    .await?;
+    let metrics_server = if metrics_enabled {
        Some(observability.metrics_surface(metrics_config).bind().await?)
    } else {
        None
    };
-
-    let storage_root = PathBuf::from(
-        env::var("CRANK_STORAGE_ROOT").unwrap_or_else(|_| "/var/lib/crank/storage".into()),
-    );
-    let bind_addr = env::var("CRANK_ADMIN_BIND").unwrap_or_else(|_| "0.0.0.0:3001".into());
-    let base_url = env::var("CRANK_BASE_URL").unwrap_or_else(|_| "http://localhost:3000".into());
-    let socket_addr: SocketAddr = bind_addr.parse()?;
-    let pool_config = PostgresPoolConfig::from_env()?;
-    let registry = PostgresRegistry::connect_with_options_and_pool_config(
-        database_options_from_env()?,
-        pool_config,
-    )
-    .await?;
    if metrics_enabled {
        spawn_postgres_pool_metrics(registry.pool().clone());
    }
+    let base_url = config
+        .runtime
+        .base_url
+        .clone()
+        .unwrap_or_else(|| "http://localhost:3000".to_owned());
    let auth_settings = AuthSettings {
-        session_secret: env::var("CRANK_SESSION_SECRET")?,
-        password_pepper: env::var("CRANK_PASSWORD_PEPPER")?,
-        session_ttl_hours: env::var("CRANK_SESSION_TTL_HOURS")
-            .ok()
-            .and_then(|value| value.parse::<i64>().ok())
-            .unwrap_or(24),
+        session_secret: config.session_secret.expose_secret().to_owned(),
+        password_pepper: config.password_pepper.expose_secret().to_owned(),
+        session_ttl_hours: config.session_ttl_hours,
        cookie_secure: base_url.starts_with("https://"),
        bootstrap_admin: BootstrapAdminConfig {
-            email: env::var("CRANK_BOOTSTRAP_ADMIN_EMAIL")?,
-            password: env::var("CRANK_BOOTSTRAP_ADMIN_PASSWORD")?,
-            display_name: env::var("CRANK_BOOTSTRAP_ADMIN_DISPLAY_NAME")
-                .unwrap_or_else(|_| "Crank Owner".into()),
+            email: config.bootstrap_email.clone(),
+            password: config.bootstrap_password.expose_secret().to_owned(),
+            display_name: config.bootstrap_display_name.clone(),
        },
    };
-    let runtime_limits = RuntimeLimits::from_env()?;
-    let cache_config = RuntimeCacheConfig::from_env()?;
+    let runtime_limits = RuntimeLimits::try_new(
+        config.runtime.max_concurrent_unary,
+        config.runtime.max_concurrent_sessions,
+    )?;
+    let cache_config = runtime_cache_config(&config)?;
    let cache_stores = RuntimeCacheStores::from_config(&cache_config).await?;
-    let api_rate_limit = admin_api_rate_limit_config_from_env()?;
-    let secret_crypto = SecretCrypto::new(&env::var("CRANK_MASTER_KEY")?)?;
-    let outbound_http_policy = crank_runtime::OutboundHttpPolicy::from_env()?;
+    let api_rate_limit = RequestRateLimitConfig::new(
+        config.rate_limit.requests_per_second,
+        config.rate_limit.burst,
+    )?;
+    let secret_crypto = SecretCrypto::new(config.runtime.master_key.expose_secret())?;
+    let outbound_http_policy = crank_runtime::OutboundHttpPolicy::try_new(
+        config.runtime.outbound.allowed_hosts.clone(),
+        config.runtime.outbound.denied_hosts.clone(),
+        config.runtime.outbound.max_response_bytes,
+    )?;
    let runtime = crank_runtime::community_with_outbound_policy(outbound_http_policy.clone())
        .with_limits(runtime_limits)
        .with_response_cache(cache_stores.response.clone())
@@ -100,7 +178,7 @@ async fn run(
        PasswordIdentityProvider::new(registry.clone(), auth_settings.password_pepper.clone());
    let service = AdminServiceBuilder::new(
        registry,
-        storage_root,
+        config.storage_root.clone(),
        auth_settings,
        secret_crypto,
        runtime,
@@ -108,12 +186,11 @@ async fn run(
    .with_outbound_http_policy(outbound_http_policy)
    .with_identity_provider(std::sync::Arc::new(identity_provider))
    .build();
-    let invocation_log_retention_days = invocation_log_retention_days_from_env()?;
    service.bootstrap_admin_user().await?;
-    if env_flag("CRANK_DEMO_SEED") {
+    if config.demo_seed {
        service.seed_demo_assets().await?;
    }
-    spawn_invocation_log_cleanup(service.clone(), invocation_log_retention_days);
+    spawn_invocation_log_cleanup(service.clone(), config.invocation_log_retention_days);
    let state = AppState {
        service,
        api_rate_limiter: if cache_config.backend.is_external() {
@@ -121,10 +198,10 @@ async fn run(
        } else {
            RequestRateLimiter::new(api_rate_limit)
        },
-        trust_forwarded_headers: env_flag("CRANK_TRUST_FORWARDED_HEADERS"),
+        trust_forwarded_headers: config.trust_forwarded_headers,
    };
    let app = build_app(state);
-    let listener = TcpListener::bind(socket_addr).await?;
+    let listener = TcpListener::bind(config.bind_addr).await?;
    let make_service = app.into_make_service_with_connect_info::<SocketAddr>();

    info!(
@@ -138,14 +215,10 @@ async fn run(
        acquire_timeout_ms = pool_config.acquire_timeout_ms,
        idle_timeout_ms = pool_config.idle_timeout_ms,
        max_lifetime_ms = pool_config.max_lifetime_ms,
-        invocation_log_retention_days,
+        invocation_log_retention_days = config.invocation_log_retention_days,
        "postgres pool configured"
    );
-    info!(
-        name: "admin.server.listening",
-        bind_address = %socket_addr,
-        "admin-api listening"
-    );
+    info!(name: "admin.server.listening", bind_address = %config.bind_addr, "admin-api listening");
    *startup_completed = true;

    if let Some(metrics_server) = metrics_server {
@@ -156,23 +229,163 @@ async fn run(
    } else {
        axum::serve(listener, make_service).await?;
    }
-
    Ok(())
 }

-fn invocation_log_retention_days_from_env() -> Result<i64, Box<dyn std::error::Error>> {
-    const NAME: &str = "CRANK_INVOCATION_LOG_RETENTION_DAYS";
-    let value = match env::var(NAME) {
-        Ok(raw) => raw.parse::<i64>()?,
-        Err(env::VarError::NotPresent) => 30,
-        Err(error) => return Err(error.into()),
-    };
-    if !(1..=MAX_INVOCATION_LOG_RETENTION_DAYS).contains(&value) {
-        return Err(
-            format!("{NAME} must be between 1 and {MAX_INVOCATION_LOG_RETENTION_DAYS}").into(),
-        );
+fn init_observability(
+    config: &ObservabilitySettings,
+) -> Result<ObservabilityLifecycle, Box<dyn std::error::Error>> {
+    let identity = ServiceIdentity::try_new(
+        "admin-api",
+        env!("CARGO_PKG_VERSION"),
+        config.environment.clone(),
+    )?;
+    let base = ObservabilityConfig::try_new(
+        identity,
+        config.log_filter.clone(),
+        RedactionLimits::default(),
+    )?;
+    let sentry = SentryConfig::parse(
+        config
+            .sentry_dsn
+            .as_ref()
+            .map(|value| value.expose_secret()),
+    )?;
+    let otlp = otlp_config(config)?;
+    Ok(ObservabilityLifecycle::init_with_exporters(
+        base, sentry, otlp,
+    )?)
+}
+
+fn preflight_config(config: &AdminProcessConfig) -> Result<(), crank_config::ConfigError> {
+    let invalid = |field| crank_config::ConfigError::single(DiagnosticCode::InvalidType, field);
+    database_options(&config.database).map_err(|_| invalid("database.source"))?;
+    postgres_pool_config(&config.database).map_err(|_| invalid("database.pool"))?;
+    MetricsConfig::new(
+        config.observability.metrics.enabled,
+        config.observability.metrics.bind_addr,
+        config
+            .observability
+            .metrics
+            .bearer_token
+            .as_ref()
+            .map(|v| v.expose_secret().to_owned()),
+    )
+    .map_err(|_| invalid("observability.metrics"))?;
+    RuntimeLimits::try_new(
+        config.runtime.max_concurrent_unary,
+        config.runtime.max_concurrent_sessions,
+    )
+    .map_err(|_| invalid("runtime.limits"))?;
+    runtime_cache_config(config).map_err(|_| invalid("cache"))?;
+    RequestRateLimitConfig::new(
+        config.rate_limit.requests_per_second,
+        config.rate_limit.burst,
+    )
+    .map_err(|_| invalid("admin.rate_limit"))?;
+    SecretCrypto::new(config.runtime.master_key.expose_secret())
+        .map_err(|_| invalid("runtime.master_key"))?;
+    crank_runtime::OutboundHttpPolicy::try_new(
+        config.runtime.outbound.allowed_hosts.clone(),
+        config.runtime.outbound.denied_hosts.clone(),
+        config.runtime.outbound.max_response_bytes,
+    )
+    .map_err(|_| invalid("runtime.outbound"))?;
+    let identity = ServiceIdentity::try_new(
+        "admin-api",
+        env!("CARGO_PKG_VERSION"),
+        config.observability.environment.clone(),
+    )
+    .map_err(|_| invalid("observability.environment"))?;
+    ObservabilityConfig::try_new(
+        identity,
+        config.observability.log_filter.clone(),
+        RedactionLimits::default(),
+    )
+    .map_err(|_| invalid("observability.log_filter"))?;
+    SentryConfig::parse(
+        config
+            .observability
+            .sentry_dsn
+            .as_ref()
+            .map(|v| v.expose_secret()),
+    )
+    .map_err(|_| invalid("observability.sentry_dsn"))?;
+    otlp_config(&config.observability).map_err(|_| invalid("observability.otlp"))?;
+    Ok(())
+}
+
+fn otlp_config(
+    config: &ObservabilitySettings,
+) -> Result<OtlpTraceConfig, crank_observability::OtlpTraceConfigError> {
+    let values = &config.otlp;
+    OtlpTraceConfig::from_values(
+        values.endpoint.clone(),
+        values.traces_endpoint.clone(),
+        values.protocol.clone(),
+        values.traces_protocol.clone(),
+        values.timeout.clone(),
+        values.traces_timeout.clone(),
+        values
+            .headers
+            .as_ref()
+            .map(|value| value.expose_secret().to_owned()),
+        values
+            .traces_headers
+            .as_ref()
+            .map(|value| value.expose_secret().to_owned()),
+        values.max_queue_size,
+        values.max_export_batch_size,
+        values.schedule_delay.clone(),
+        values.export_timeout.clone(),
+    )
+}
+
+fn postgres_pool_config(
+    config: &DatabaseSettings,
+) -> Result<PostgresPoolConfig, crank_registry::PostgresPoolConfigError> {
+    PostgresPoolConfig::try_new(
+        config.pool.max_connections,
+        config.pool.min_connections,
+        config.pool.acquire_timeout_ms,
+        config.pool.idle_timeout_ms,
+        config.pool.max_lifetime_ms,
+    )
+}
+
+fn database_options(
+    config: &DatabaseSettings,
+) -> Result<PgConnectOptions, Box<dyn std::error::Error>> {
+    if let Some(url) = &config.url {
+        return url
+            .expose_secret()
+            .parse::<PgConnectOptions>()
+            .map_err(|_| io::Error::other("database URL is invalid").into());
    }
-    Ok(value)
+    Ok(PgConnectOptions::new()
+        .host(&config.host)
+        .port(config.port)
+        .database(&config.database)
+        .username(&config.username)
+        .password(config.password.expose_secret()))
+}
+
+fn runtime_cache_config(
+    config: &AdminProcessConfig,
+) -> Result<RuntimeCacheConfig, crank_runtime::RuntimeCacheConfigError> {
+    RuntimeCacheConfig::try_new(
+        match config.runtime.cache.backend {
+            ConfigCacheBackend::Memory => CacheBackend::Memory,
+            ConfigCacheBackend::Valkey => CacheBackend::Valkey,
+            ConfigCacheBackend::Redis => CacheBackend::Redis,
+        },
+        config
+            .runtime
+            .cache
+            .url
+            .as_ref()
+            .map(|value| value.expose_secret().to_owned()),
+    )
 }

 fn spawn_invocation_log_cleanup(service: admin_api::service::AdminService, retention_days: i64) {
@@ -197,50 +410,3 @@ fn spawn_invocation_log_cleanup(service: admin_api::service::AdminService, reten
        }
    });
 }
-
-fn env_flag(name: &str) -> bool {
-    matches!(
-        env::var(name)
-            .ok()
-            .as_deref()
-            .map(str::to_ascii_lowercase)
-            .as_deref(),
-        Some("1" | "true" | "yes" | "on")
-    )
-}
-
-fn admin_api_rate_limit_config_from_env()
-> Result<RequestRateLimitConfig, Box<dyn std::error::Error>> {
-    let requests_per_second = env::var("CRANK_ADMIN_RATE_LIMIT_RPS")
-        .ok()
-        .and_then(|value| value.parse::<u32>().ok())
-        .unwrap_or(30);
-    let burst = env::var("CRANK_ADMIN_RATE_LIMIT_BURST")
-        .ok()
-        .and_then(|value| value.parse::<u32>().ok())
-        .unwrap_or(60);
-
-    Ok(RequestRateLimitConfig::new(requests_per_second, burst)?)
-}
-
-fn database_options_from_env() -> Result<PgConnectOptions, Box<dyn std::error::Error>> {
-    if let Ok(database_url) = env::var("CRANK_DATABASE_URL") {
-        return Ok(database_url.parse::<PgConnectOptions>()?);
-    }
-
-    let host = env::var("POSTGRES_HOST").unwrap_or_else(|_| "postgres".into());
-    let port = env::var("POSTGRES_PORT")
-        .ok()
-        .and_then(|value| value.parse::<u16>().ok())
-        .unwrap_or(5432);
-    let database = env::var("POSTGRES_DB").unwrap_or_else(|_| "crank".into());
-    let username = env::var("POSTGRES_USER").unwrap_or_else(|_| "crank".into());
-    let password = env::var("POSTGRES_PASSWORD").unwrap_or_else(|_| "crank".into());
-
-    Ok(PgConnectOptions::new()
-        .host(&host)
-        .port(port)
-        .database(&database)
-        .username(&username)
-        .password(&password))
-}
@@ -4,20 +4,30 @@ use axum::{
    middleware::Next,
    response::Response,
 };
-use crank_observability::{RequestId, set_remote_trace_parent, with_request_correlation};
+use crank_core::{CorrelationContext, RequestId, TraceContext};
+use crank_observability::{set_remote_trace_parent, with_request_correlation};
 use tracing::{Instrument, info, info_span};

 pub const REQUEST_ID_HEADER: HeaderName = HeaderName::from_static("x-request-id");
+pub const TRACE_ID_HEADER: HeaderName = HeaderName::from_static("x-trace-id");

 #[derive(Clone, Debug)]
 pub struct RequestContext {
-    pub request_id: String,
+    pub correlation: CorrelationContext,
+}
+
+impl RequestContext {
+    pub fn request_id(&self) -> &str {
+        self.correlation.request_id().as_str()
+    }
+
+    pub fn trace_id(&self) -> &str {
+        self.correlation.trace_id().as_str()
+    }
 }

 pub async fn apply_request_context(mut request: Request, next: Next) -> Response {
-    let context = RequestContext {
-        request_id: RequestId::resolve_from_headers(request.headers()).into_string(),
-    };
+    let (request_id, remote_parent) = resolve_correlation(request.headers());
    let method = request.method().clone();
    let route = request
        .extensions()
@@ -27,41 +37,105 @@ pub async fn apply_request_context(mut request: Request, next: Next) -> Response
    let span = info_span!(
        target: "crank::trace",
        "http.request",
-        request_id = %context.request_id,
+        request_id = %request_id,
+        trace_id = tracing::field::Empty,
    );
-    set_remote_trace_parent(&span, request.headers());
+    if let Some(remote_parent) = remote_parent.as_ref() {
+        set_canonical_parent(&span, remote_parent);
+    }
+    let trace_context = crank_trace::trace_context_for_span(&span).unwrap_or_else(|| {
+        remote_parent
+            .as_ref()
+            .map_or_else(TraceContext::generate, TraceContext::continue_local)
+    });
+    span.record("trace_id", trace_context.trace_id().as_str());
+    let context = RequestContext {
+        correlation: CorrelationContext::new(request_id, trace_context),
+    };
    request.extensions_mut().insert(context.clone());

-    with_request_correlation(context.request_id.clone(), async move {
+    with_request_correlation(
+        context.correlation.request_id().to_string(),
+        context.correlation.trace_id().to_string(),
+        async move {
            let mut response = next.run(request).instrument(span).await;
            info!(
                name: "admin.request.completed",
-            request_id = %context.request_id,
+                request_id = %context.correlation.request_id(),
+                trace_id = %context.correlation.trace_id(),
                method = %method,
                route,
                status = response.status().as_u16(),
                "admin request completed"
            );
-        if let Ok(value) = HeaderValue::from_str(&context.request_id) {
+            if let Ok(value) = HeaderValue::from_str(context.correlation.request_id().as_str()) {
                response.headers_mut().insert(REQUEST_ID_HEADER, value);
            }
+            if let Ok(value) = HeaderValue::from_str(context.correlation.trace_id().as_str()) {
+                response.headers_mut().insert(TRACE_ID_HEADER, value);
+            }
            response
-    })
+        },
+    )
    .await
 }

+fn resolve_correlation(headers: &axum::http::HeaderMap) -> (RequestId, Option<TraceContext>) {
+    let _tracestate_accepted = one_auxiliary_header_within_budget(
+        headers,
+        "tracestate",
+        TraceContext::tracestate_within_budget,
+    );
+    let _baggage_accepted =
+        one_auxiliary_header_within_budget(headers, "baggage", TraceContext::baggage_within_budget);
+    let mut request_ids = headers.get_all(REQUEST_ID_HEADER).iter();
+    let request_id = request_ids.next().and_then(|value| value.to_str().ok());
+    let request_id = if request_ids.next().is_some() {
+        RequestId::generate()
+    } else {
+        RequestId::resolve(request_id)
+    };
+
+    let mut traceparents = headers.get_all("traceparent").iter();
+    let traceparent = traceparents.next().and_then(|value| value.to_str().ok());
+    let remote_parent = if traceparents.next().is_some() {
+        None
+    } else {
+        traceparent.and_then(|value| TraceContext::parse(value).ok())
+    };
+    (request_id, remote_parent)
+}
+
+fn one_auxiliary_header_within_budget(
+    headers: &axum::http::HeaderMap,
+    name: &'static str,
+    validate: fn(&str) -> bool,
+) -> bool {
+    let mut values = headers.get_all(name).iter();
+    let value = values.next().and_then(|value| value.to_str().ok());
+    values.next().is_none() && value.is_some_and(validate)
+}
+
+fn set_canonical_parent(span: &tracing::Span, context: &TraceContext) {
+    let mut headers = axum::http::HeaderMap::new();
+    if let Ok(value) = HeaderValue::from_str(context.traceparent()) {
+        headers.insert("traceparent", value);
+        set_remote_trace_parent(span, &headers);
+    }
+}
+
 #[cfg(test)]
 mod tests {
    #[test]
    fn accepts_visible_ascii_request_ids() {
-        assert!(crank_observability::RequestId::is_valid("req_test_123"));
-        assert!(crank_observability::RequestId::is_valid("trace-123/abc"));
+        assert!(crank_core::RequestId::is_valid("req_test_123"));
+        assert!(crank_core::RequestId::is_valid("trace-123/abc"));
    }

    #[test]
    fn rejects_empty_or_control_request_ids() {
-        assert!(!crank_observability::RequestId::is_valid(""));
-        assert!(!crank_observability::RequestId::is_valid("bad value"));
-        assert!(!crank_observability::RequestId::is_valid("bad\nvalue"));
+        assert!(!crank_core::RequestId::is_valid(""));
+        assert!(!crank_core::RequestId::is_valid("bad value"));
+        assert!(!crank_core::RequestId::is_valid("bad\nvalue"));
    }
 }
@@ -193,7 +193,7 @@ pub async fn run_test(
            &path.workspace_id.as_str().into(),
            &path.operation_id.as_str().into(),
            payload,
-            &request_context.request_id,
+            &request_context.correlation,
        )
        .await?;
    Ok(Json(json!(result)))
@@ -469,6 +469,7 @@ impl AdminService {
            tool_name: request.operation.name.clone(),
            message: request.message,
            request_id: request.request_id.map(ToOwned::to_owned),
+            trace_id: request.trace_id.map(ToOwned::to_owned),
            status_code: request.status_code,
            duration_ms: request.duration_ms,
            error_kind: request.error_kind,
@@ -506,6 +507,7 @@ impl AdminService {
        observe_invocation_history_outcome(
            outcome,
            request.request_id,
+            request.trace_id,
            request.status,
            request.source,
        );
@@ -516,6 +518,7 @@ impl AdminService {
 fn observe_invocation_history_outcome(
    outcome: InvocationHistoryWriteOutcome,
    request_id: Option<&str>,
+    trace_id: Option<&str>,
    status: crank_core::InvocationStatus,
    source: InvocationSource,
 ) {
@@ -528,6 +531,7 @@ fn observe_invocation_history_outcome(
    tracing::warn!(
        name: "admin.invocation_history.lost",
        request_id = request_id.unwrap_or_default(),
+        trace_id = trace_id.unwrap_or_default(),
        source = invocation_source_label(source),
        invocation_status = invocation_status_label(status),
        error_category = loss.category.as_str(),
@@ -935,6 +939,7 @@ mod tests {
                category: InvocationHistoryLossCategory::InvalidRecord,
            }),
            Some("req_admin_dc08"),
+            Some("0af7651916cd43dd8448eb211c80319c"),
            InvocationStatus::Error,
            InvocationSource::AgentToolCall,
        );
@@ -316,11 +316,13 @@ impl AdminService {
                    .current_draft_version,
            )
            .await?;
+        let correlation = crank_core::CorrelationContext::generate();
        self.record_invocation(InvocationRecordRequest {
            workspace_id,
            agent_id: Some(currency_agent_id),
            operation: &rest_operation.snapshot,
-            request_id: None,
+            request_id: Some(correlation.request_id().as_str()),
+            trace_id: Some(correlation.trace_id().as_str()),
            source: InvocationSource::AgentToolCall,
            level: InvocationLevel::Info,
            status: InvocationStatus::Ok,
@@ -444,9 +444,11 @@ impl AdminService {
        workspace_id: &WorkspaceId,
        operation_id: &OperationId,
        payload: TestRunPayload,
-        request_id: &str,
+        correlation: &crank_core::CorrelationContext,
    ) -> Result<TestRunResult, ApiError> {
-        let runtime_request_context = RuntimeRequestContext::from_request_id(request_id)
+        let request_id = correlation.request_id().as_str();
+        let trace_id = correlation.trace_id().as_str();
+        let runtime_request_context = RuntimeRequestContext::from_correlation(correlation)
            .with_metering_context(workspace_id.clone(), None, InvocationSource::AdminTestRun);
        let record = self
            .get_operation_version(workspace_id, operation_id, payload.version)
@@ -467,6 +469,7 @@ impl AdminService {
                    agent_id: None,
                    operation: &record.snapshot,
                    request_id: Some(request_id),
+                    trace_id: Some(trace_id),
                    source: InvocationSource::AdminTestRun,
                    level: InvocationLevel::Error,
                    status: InvocationStatus::Error,
@@ -516,6 +519,7 @@ impl AdminService {
                    agent_id: None,
                    operation: &record.snapshot,
                    request_id: Some(request_id),
+                    trace_id: Some(trace_id),
                    source: InvocationSource::AdminTestRun,
                    level: InvocationLevel::Info,
                    status: InvocationStatus::Ok,
@@ -543,6 +547,7 @@ impl AdminService {
                    agent_id: None,
                    operation: &record.snapshot,
                    request_id: Some(request_id),
+                    trace_id: Some(trace_id),
                    source: InvocationSource::AdminTestRun,
                    level: InvocationLevel::Error,
                    status: InvocationStatus::Error,
@@ -0,0 +1,71 @@
+use std::process::Command;
+
+fn run_with(entries: &[(&str, &str)]) -> String {
+    let mut command = Command::new(env!("CARGO_BIN_EXE_admin-api"));
+    for field in crank_config::field_registry() {
+        command.env_remove(field.env_name);
+    }
+    command.envs([
+        ("CRANK_MASTER_KEY", "master"),
+        ("CRANK_SESSION_SECRET", "session"),
+        ("CRANK_PASSWORD_PEPPER", "pepper"),
+        ("CRANK_BOOTSTRAP_ADMIN_EMAIL", "owner@example.test"),
+        ("CRANK_BOOTSTRAP_ADMIN_PASSWORD", "password"),
+    ]);
+    for (name, value) in entries {
+        command.env(name, value);
+    }
+    let output = command.output().expect("admin binary executes");
+    assert!(!output.status.success());
+    let stderr = String::from_utf8(output.stderr).expect("stderr is UTF-8");
+    assert!(!stderr.contains("CANARY_SECRET_VALUE"));
+    assert!(!stderr.contains("connection refused"));
+    assert!(stderr.len() <= 65_536);
+    stderr
+}
+
+#[test]
+fn invalid_config_fails_before_database_or_listener_side_effects() {
+    for (entries, code) in [
+        (
+            vec![("CRANK_CONFIG_CANARY_UNKNOWN", "CANARY_SECRET_VALUE")],
+            "config.unknown_field",
+        ),
+        (vec![("POSTGRES_PORT", "bad")], "config.invalid_type"),
+        (
+            vec![
+                ("CRANK_DATABASE_URL", "postgres://db/crank"),
+                ("POSTGRES_HOST", "other"),
+            ],
+            "config.conflict",
+        ),
+        (vec![("CRANK_LOG_LEVEL", "[")], "config.invalid_type"),
+    ] {
+        let stderr = run_with(&entries);
+        assert!(stderr.contains(code), "{stderr}");
+    }
+}
+
+#[test]
+fn database_driver_failures_are_normalized_and_redacted() {
+    let stderr = run_with(&[(
+        "CRANK_DATABASE_URL",
+        "postgres://CANARY_SECRET_VALUE:CANARY_SECRET_VALUE@127.0.0.1:1/crank",
+    )]);
+    assert!(stderr.contains("startup_failed"), "{stderr}");
+}
+
+#[tokio::test]
+async fn fresh_database_startup_is_read_only() {
+    let database_url = crank_test_support::postgres_schema_url("admin_startup_read_only").await;
+    let stderr = run_with(&[("CRANK_DATABASE_URL", &database_url)]);
+    assert!(stderr.contains("schema_missing"), "{stderr}");
+    let pool = sqlx::PgPool::connect(&database_url).await.unwrap();
+    let present: bool = sqlx::query_scalar(
+        "select to_regclass(format('%I.%I', current_schema(), '__crank_core_migrations')) is not null",
+    )
+    .fetch_one(&pool)
+    .await
+    .unwrap();
+    assert!(!present);
+}
@@ -4,5 +4,6 @@ mod integration {
    mod community_access_usage;
    mod openapi_import;
    mod operations_agents;
+    mod request_context;
    mod secrets_import_auth;
 }
@@ -211,6 +211,10 @@ pub(super) async fn create_lead(Json(payload): Json<Value>) -> Json<Value> {

 pub(super) async fn test_registry() -> PostgresRegistry {
    let database_url = crank_test_support::postgres_schema_url("test_admin_api").await;
+    let pool = sqlx::PgPool::connect(&database_url).await.unwrap();
+    crank_registry::MigrationAuthority::apply(&pool)
+        .await
+        .unwrap();
    let registry = PostgresRegistry::connect(&database_url).await.unwrap();
    let password_hash = hash_password(TEST_AUTH_PASSWORD, TEST_PASSWORD_PEPPER).unwrap();
    let user_id = registry
@@ -10,7 +10,7 @@ use std::{
 };

 use async_trait::async_trait;
-use axum::{Json, Router, routing::post};
+use axum::{Json, Router, extract::State, http::HeaderMap, routing::post};
 use crank_core::{
    ExecutionConfig, HttpMethod, MembershipRole, OperationSecurityLevel, Protocol,
    ResponseCachePolicy, RestTarget, SecretKind, Target, ToolDescription, WorkspaceId,
@@ -97,8 +97,8 @@ impl IdentityProvider for RejectingIdentityProvider {
 async fn creates_publishes_and_tests_rest_operation() {
    let registry = test_registry().await;
    let storage_root = test_storage_root("lifecycle");
-    let upstream_base_url = spawn_upstream_server().await;
-    let base_url = spawn_admin_api(build_test_app(registry, storage_root)).await;
+    let (upstream_base_url, observed_upstream_headers) = spawn_correlation_upstream_server().await;
+    let base_url = spawn_admin_api(build_test_app(registry.clone(), storage_root)).await;
    let client = authorized_client(&base_url).await;

    let created = client
@@ -132,18 +132,25 @@ async fn creates_publishes_and_tests_rest_operation() {
        .json::<Value>()
        .await
        .unwrap();
-    let test_run = client
+    let test_run_response = client
        .post(format!("{base_url}/operations/{operation_id}/test-runs"))
+        .header("x-request-id", "req_admin_test_run")
+        .header(
+            "traceparent",
+            "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
+        )
        .json(&json!({
            "version": 1,
            "input": { "email": "user@example.com" }
        }))
        .send()
        .await
-        .unwrap()
-        .json::<Value>()
-        .await
        .unwrap();
+    assert_eq!(
+        test_run_response.headers()["x-trace-id"].to_str().unwrap(),
+        "0af7651916cd43dd8448eb211c80319c"
+    );
+    let test_run = test_run_response.json::<Value>().await.unwrap();

    assert_eq!(listed["items"][0]["name"], "crm_create_lead");
    assert_eq!(
@@ -158,6 +165,65 @@ async fn creates_publishes_and_tests_rest_operation() {
        "user@example.com"
    );
    assert_eq!(test_run["response_preview"]["id"], "lead_123");
+    let logs = registry
+        .list_invocation_logs(crank_registry::ListInvocationLogsQuery {
+            workspace_id: &WorkspaceId::new(DEFAULT_WORKSPACE_ID),
+            level: None,
+            search_text: None,
+            source: Some(crank_core::InvocationSource::AdminTestRun),
+            operation_id: Some(&crank_core::OperationId::new(&operation_id)),
+            agent_id: None,
+            created_after: None,
+            limit: 10,
+        })
+        .await
+        .unwrap();
+    assert_eq!(logs.len(), 1);
+    assert_eq!(
+        logs[0].log.request_id.as_deref(),
+        Some("req_admin_test_run")
+    );
+    assert_eq!(
+        logs[0].log.trace_id.as_deref(),
+        Some("0af7651916cd43dd8448eb211c80319c")
+    );
+    let upstream_headers = observed_upstream_headers.lock().await;
+    let upstream_headers = upstream_headers.as_ref().unwrap();
+    assert_eq!(
+        upstream_headers["x-request-id"].to_str().unwrap(),
+        "req_admin_test_run"
+    );
+    assert_eq!(
+        &upstream_headers["traceparent"].to_str().unwrap()[3..35],
+        "0af7651916cd43dd8448eb211c80319c"
+    );
+}
+
+async fn spawn_correlation_upstream_server() -> (String, Arc<tokio::sync::Mutex<Option<HeaderMap>>>)
+{
+    let observed = Arc::new(tokio::sync::Mutex::new(None));
+    let app = Router::new()
+        .route("/crm/leads", post(capture_correlation_and_create_lead))
+        .with_state(Arc::clone(&observed));
+    let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let address = listener.local_addr().unwrap();
+    tokio::spawn(async move {
+        axum::serve(listener, app).await.unwrap();
+    });
+    (format!("http://{address}"), observed)
+}
+
+async fn capture_correlation_and_create_lead(
+    State(observed): State<Arc<tokio::sync::Mutex<Option<HeaderMap>>>>,
+    headers: HeaderMap,
+    Json(payload): Json<Value>,
+) -> Json<Value> {
+    *observed.lock().await = Some(headers);
+    Json(json!({
+        "id": "lead_123",
+        "status": "created",
+        "input": payload,
+    }))
 }

 #[tokio::test(flavor = "multi_thread")]
@@ -3,10 +3,10 @@ use std::{
    sync::{Arc, Mutex},
 };

-use admin_api::request_context::{REQUEST_ID_HEADER, apply_request_context};
+use admin_api::request_context::{REQUEST_ID_HEADER, TRACE_ID_HEADER, apply_request_context};
 use axum::{
    Router,
-    body::Body,
+    body::{Body, to_bytes},
    http::{HeaderMap, HeaderValue, Request, StatusCode},
    routing::get,
 };
@@ -64,6 +64,11 @@ async fn logs_request_completion_and_rejects_untrusted_values() {
        .find(|event: &serde_json::Value| event["event"] == "admin.request.completed")
        .unwrap();
    assert_eq!(event["request_id"], "req_admin_trace_123");
+    let trace_id = response.headers()[TRACE_ID_HEADER.as_str()]
+        .to_str()
+        .unwrap();
+    assert_eq!(trace_id.len(), 32);
+    assert_eq!(event["trace_id"], trace_id);
    assert_eq!(event["fields"]["status"], 200);
    assert_eq!(event["fields"]["route"], "/probe");

@@ -85,9 +90,144 @@ async fn logs_request_completion_and_rejects_untrusted_values() {
        uuid::Uuid::parse_str(generated).unwrap().get_version(),
        Some(Version::SortRand)
    );
+    let generated_trace = invalid_response.headers()[TRACE_ID_HEADER.as_str()]
+        .to_str()
+        .unwrap();
+    assert_eq!(generated_trace.len(), 32);
+    assert_ne!(generated_trace, "canary-invalid-traceparent");
    assert!(!writer.output().contains("canary-invalid-traceparent"));
 }

+#[tokio::test(flavor = "current_thread")]
+async fn structured_boundary_error_carries_the_same_safe_ids() {
+    let _tracing_test_guard = TRACING_TEST_LOCK.lock().await;
+    let dispatch = tracing::Dispatch::new(tracing_subscriber::registry());
+    let _dispatch_guard = tracing::dispatcher::set_default(&dispatch);
+    let response = error_probe_app()
+        .oneshot(
+            Request::builder()
+                .uri("/error")
+                .header("x-request-id", "request-boundary-error")
+                .header(
+                    "traceparent",
+                    "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
+                )
+                .body(Body::empty())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+    assert_eq!(
+        response.headers()[REQUEST_ID_HEADER],
+        "request-boundary-error"
+    );
+    assert_eq!(
+        response.headers()[TRACE_ID_HEADER],
+        "0af7651916cd43dd8448eb211c80319c"
+    );
+    let body = to_bytes(response.into_body(), 16 * 1024).await.unwrap();
+    let payload: serde_json::Value = serde_json::from_slice(&body).unwrap();
+    assert_eq!(payload["error"]["request_id"], "request-boundary-error");
+    assert_eq!(
+        payload["error"]["trace_id"],
+        "0af7651916cd43dd8448eb211c80319c"
+    );
+}
+
+#[tokio::test(flavor = "current_thread")]
+async fn boundary_status_matrix_keeps_ids_and_redacts_internal_causes() {
+    let _tracing_test_guard = TRACING_TEST_LOCK.lock().await;
+    let writer = SharedLogWriter::default();
+    let subscriber = crank_observability::build_subscriber(
+        ObservabilityConfig::new(
+            ServiceIdentity::try_new("admin-api", "test", "test").unwrap(),
+            "info",
+            RedactionLimits::default(),
+        ),
+        writer.clone(),
+    )
+    .unwrap();
+    let app = Router::new()
+        .route(
+            "/bad-request",
+            get(|| async { Err::<(), _>(admin_api::error::ApiError::validation("invalid")) }),
+        )
+        .route(
+            "/unauthorized",
+            get(|| async {
+                Err::<(), _>(admin_api::error::ApiError::unauthorized("unauthorized"))
+            }),
+        )
+        .route(
+            "/forbidden",
+            get(|| async { Err::<(), _>(admin_api::error::ApiError::forbidden("forbidden")) }),
+        )
+        .route(
+            "/internal",
+            get(|| async {
+                Err::<(), _>(admin_api::error::ApiError::internal(
+                    "postgres://canary-user:canary-password@private-host/database",
+                ))
+            }),
+        )
+        .route(
+            "/rate-limited",
+            get(|| async { StatusCode::TOO_MANY_REQUESTS }),
+        )
+        .layer(axum::middleware::from_fn(apply_request_context));
+
+    let responses = async {
+        let mut responses = Vec::new();
+        for (path, status) in [
+            ("/bad-request", StatusCode::BAD_REQUEST),
+            ("/unauthorized", StatusCode::UNAUTHORIZED),
+            ("/forbidden", StatusCode::FORBIDDEN),
+            ("/missing", StatusCode::NOT_FOUND),
+            ("/rate-limited", StatusCode::TOO_MANY_REQUESTS),
+            ("/internal", StatusCode::INTERNAL_SERVER_ERROR),
+        ] {
+            let response = app
+                .clone()
+                .oneshot(
+                    Request::builder()
+                        .uri(path)
+                        .header(REQUEST_ID_HEADER.as_str(), "matrix-request-id")
+                        .body(Body::empty())
+                        .unwrap(),
+                )
+                .await
+                .unwrap();
+            assert_eq!(response.status(), status);
+            assert_eq!(response.headers()[REQUEST_ID_HEADER], "matrix-request-id");
+            assert_eq!(response.headers()[TRACE_ID_HEADER].as_bytes().len(), 32);
+            responses.push(to_bytes(response.into_body(), 16 * 1024).await.unwrap());
+        }
+        responses
+    };
+    let dispatch = tracing::Dispatch::new(subscriber);
+    let _dispatch_guard = tracing::dispatcher::set_default(&dispatch);
+    let responses = responses.await;
+    let combined = responses
+        .iter()
+        .flat_map(|body| body.iter().copied())
+        .collect::<Vec<_>>();
+    assert!(
+        !combined
+            .windows("canary-password".len())
+            .any(|value| value == b"canary-password")
+    );
+    assert!(!writer.output().contains("canary-password"));
+    let internal_event: serde_json::Value = writer
+        .output()
+        .lines()
+        .map(|line| serde_json::from_str(line).unwrap())
+        .find(|event: &serde_json::Value| event["event"] == "admin.response.internal_error")
+        .unwrap();
+    assert_eq!(internal_event["request_id"], "matrix-request-id");
+    assert_eq!(internal_event["trace_id"].as_str().unwrap().len(), 32);
+}
+
 #[tokio::test(flavor = "current_thread")]
 async fn covers_valid_invalid_and_absent_traceparent() {
    let _tracing_test_guard = TRACING_TEST_LOCK.lock().await;
@@ -163,6 +303,14 @@ async fn replaces_multiple_request_id_headers_with_one_uuid_v7() {
        REQUEST_ID_HEADER,
        HeaderValue::from_static("second-request-id"),
    );
+    request.headers_mut().append(
+        "traceparent",
+        HeaderValue::from_static("00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"),
+    );
+    request.headers_mut().append(
+        "traceparent",
+        HeaderValue::from_static("00-1af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"),
+    );

    let response = probe_app().oneshot(request).await.unwrap();
    let generated = response.headers()[REQUEST_ID_HEADER].to_str().unwrap();
@@ -173,6 +321,9 @@ async fn replaces_multiple_request_id_headers_with_one_uuid_v7() {
        uuid::Uuid::parse_str(generated).unwrap().get_version(),
        Some(Version::SortRand)
    );
+    let trace_id = response.headers()[TRACE_ID_HEADER].to_str().unwrap();
+    assert_ne!(trace_id, "0af7651916cd43dd8448eb211c80319c");
+    assert_ne!(trace_id, "1af7651916cd43dd8448eb211c80319c");
 }

 fn probe_app() -> Router {
@@ -181,6 +332,15 @@ fn probe_app() -> Router {
        .layer(axum::middleware::from_fn(apply_request_context))
 }

+fn error_probe_app() -> Router {
+    Router::new()
+        .route(
+            "/error",
+            get(|| async { Err::<(), _>(admin_api::error::ApiError::validation("invalid")) }),
+        )
+        .layer(axum::middleware::from_fn(apply_request_context))
+}
+
 fn trace_probe_app() -> Router {
    Router::new()
        .route("/trace", get(observed_traceparent))
@@ -0,0 +1,90 @@
+use std::process::{Command, Output};
+
+fn command(arguments: &[&str], database_url: Option<&str>) -> Output {
+    let mut command = Command::new(env!("CARGO_BIN_EXE_crank-migrate"));
+    command.args(arguments);
+    command.current_dir(std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../.."));
+    for (name, _) in std::env::vars() {
+        if name.starts_with("CRANK_") || name.starts_with("POSTGRES_") || name.starts_with("OTEL_")
+        {
+            command.env_remove(name);
+        }
+    }
+    if let Some(database_url) = database_url {
+        command.env("CRANK_DATABASE_URL", database_url);
+    }
+    command.output().expect("migration command must run")
+}
+
+#[test]
+fn plan_is_deterministic_and_committed_contract_is_current() {
+    let first = command(&["plan"], None);
+    let second = command(&["plan"], None);
+    assert!(
+        first.status.success(),
+        "{}",
+        String::from_utf8_lossy(&first.stderr)
+    );
+    assert_eq!(first.stdout, second.stdout);
+    let plan: serde_json::Value = serde_json::from_slice(&first.stdout).unwrap();
+    assert_eq!(plan["sequence"].as_array().unwrap().len(), 3);
+
+    let checked = command(&["plan", "--check"], None);
+    assert!(
+        checked.status.success(),
+        "{}",
+        String::from_utf8_lossy(&checked.stderr)
+    );
+}
+
+#[test]
+fn invalid_command_is_bounded_and_does_not_echo_arguments() {
+    let canary = "secret-command-canary";
+    let output = command(&[canary], None);
+    assert!(!output.status.success());
+    let stderr = String::from_utf8(output.stderr).unwrap();
+    assert!(stderr.len() < 1_024);
+    assert!(!stderr.contains(canary));
+    let diagnostic: serde_json::Value = serde_json::from_str(stderr.trim()).unwrap();
+    assert_eq!(diagnostic["code"], "invalid_command");
+}
+
+#[tokio::test]
+async fn database_only_config_can_apply_and_preflight_a_fresh_schema() {
+    let database_url = crank_test_support::postgres_schema_url("test_migration_command").await;
+    let applied = command(&["apply"], Some(&database_url));
+    assert!(
+        applied.status.success(),
+        "{}",
+        String::from_utf8_lossy(&applied.stderr)
+    );
+    let result: serde_json::Value = serde_json::from_slice(&applied.stdout).unwrap();
+    assert_eq!(result["status"], "applied");
+
+    let preflight = command(&["preflight"], Some(&database_url));
+    assert!(
+        preflight.status.success(),
+        "{}",
+        String::from_utf8_lossy(&preflight.stderr)
+    );
+    let result: serde_json::Value = serde_json::from_slice(&preflight.stdout).unwrap();
+    assert_eq!(result["status"], "current");
+    assert_eq!(result["version"], 3);
+}
+
+#[tokio::test]
+async fn migration_error_json_preserves_affected_version() {
+    let database_url = crank_test_support::postgres_schema_url("test_migration_cli_version").await;
+    assert!(command(&["apply"], Some(&database_url)).status.success());
+    let pool = sqlx::PgPool::connect(&database_url).await.unwrap();
+    sqlx::query("update __crank_migrations set checksum = 'tampered' where version = 2")
+        .execute(&pool)
+        .await
+        .unwrap();
+
+    let output = command(&["preflight"], Some(&database_url));
+    assert!(!output.status.success());
+    let diagnostic: serde_json::Value = serde_json::from_slice(&output.stderr).unwrap();
+    assert_eq!(diagnostic["code"], "checksum_mismatch");
+    assert_eq!(diagnostic["version"], 2);
+}
@@ -13,27 +13,19 @@ fn runtime_test_failure_includes_structured_context() {
    assert_eq!(
        payload["context"],
        json!({
-            "field": "request.headers",
-            "reason": "must be an object"
+            "field": "request.headers"
        })
    );
 }

 #[test]
-fn runtime_error_context_includes_secret_crypto_operation() {
+fn runtime_error_context_does_not_expose_secret_crypto_details() {
    let context = runtime_error_context(&RuntimeError::SecretCrypto {
        operation: "decode secret envelope",
        details: "bad base64".to_owned(),
-    })
-    .unwrap();
+    });

-    assert_eq!(
-        context,
-        json!({
-            "operation": "decode secret envelope",
-            "details": "bad base64"
-        })
-    );
+    assert_eq!(context, None);
 }

 #[test]
@@ -15,6 +15,7 @@ async-trait = "0.1"
 axum.workspace = true
 base64.workspace = true
 crank-community-mcp = { path = "../../crates/crank-community-mcp" }
+crank-config = { path = "../../crates/crank-config" }
 crank-core = { path = "../../crates/crank-core" }
 crank-observability = { path = "../../crates/crank-observability" }
 crank-registry = { path = "../../crates/crank-registry" }
@@ -31,9 +31,9 @@ RUN mkdir -p \
    && printf 'pub fn placeholder() {}\n' > crates/crank-runtime/src/lib.rs \
    && printf 'pub fn placeholder() {}\n' > crates/crank-adapter-rest/src/lib.rs

-RUN --mount=type=cache,target=/usr/local/cargo/registry \
-    --mount=type=cache,target=/usr/local/cargo/git/db \
-    --mount=type=cache,target=/app/target \
+RUN --mount=type=cache,id=crank-mcp-cargo-registry,target=/usr/local/cargo/registry \
+    --mount=type=cache,id=crank-mcp-cargo-git,target=/usr/local/cargo/git/db \
+    --mount=type=cache,id=crank-mcp-target,target=/app/target \
    SQLX_OFFLINE=true cargo build --release -p mcp-server

 FROM rust:1.96.1-bookworm AS builder
@@ -45,9 +45,9 @@ COPY .sqlx ./.sqlx
 COPY apps ./apps
 COPY crates ./crates

-RUN --mount=type=cache,target=/usr/local/cargo/registry \
-    --mount=type=cache,target=/usr/local/cargo/git/db \
-    --mount=type=cache,target=/app/target \
+RUN --mount=type=cache,id=crank-mcp-cargo-registry,target=/usr/local/cargo/registry \
+    --mount=type=cache,id=crank-mcp-cargo-git,target=/usr/local/cargo/git/db \
+    --mount=type=cache,id=crank-mcp-target,target=/app/target \
    SQLX_OFFLINE=true cargo build --release -p mcp-server \
    && cp /app/target/release/mcp-server /tmp/mcp-server

@@ -1,12 +1,17 @@
-use std::{env, net::SocketAddr, time::Duration};
+use std::{io, process::ExitCode, time::Duration};

 use crank_community_mcp::{
    auth::CommunityMachineCredentialVerifier, build_app_with_background_workers_and_limits,
    session::PostgresTransportSessionStore,
 };
+use crank_config::{
+    CacheBackend as ConfigCacheBackend, ConfigSource, DatabaseSettings, DiagnosticCode,
+    McpProcessConfig, ObservabilitySettings, ProcessKind, parse_process,
+};
+use crank_core::CacheBackend;
 use crank_observability::{
    CriticalErrorCategory, MetricsConfig, ObservabilityConfig, ObservabilityLifecycle,
-    capture_critical_error,
+    OtlpTraceConfig, RedactionLimits, SentryConfig, ServiceIdentity, capture_critical_error,
 };
 use crank_registry::{PostgresPoolConfig, PostgresRegistry};
 use crank_runtime::{
@@ -19,14 +24,76 @@ use tokio::net::TcpListener;
 use tracing::info;

 #[tokio::main]
-async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let observability = crank_observability::init(ObservabilityConfig::from_env(
-        "mcp-server",
-        env!("CARGO_PKG_VERSION"),
-        "mcp_server=info,tower_http=info",
-    )?)?;
+async fn main() -> ExitCode {
+    match main_result().await {
+        Ok(()) => ExitCode::SUCCESS,
+        Err(error) => {
+            eprintln!("{}", safe_startup_diagnostic(error.as_ref()));
+            ExitCode::FAILURE
+        }
+    }
+}
+
+fn safe_startup_diagnostic(error: &(dyn std::error::Error + 'static)) -> String {
+    let mut current = Some(error);
+    while let Some(cause) = current {
+        if let Some(config) = cause.downcast_ref::<crank_config::ConfigError>() {
+            return config.to_json();
+        }
+        if let Some(migration) = cause.downcast_ref::<crank_registry::MigrationError>() {
+            return serde_json::json!({
+                "status": "error",
+                "code": migration.code(),
+                "stage": migration.stage(),
+                "version": migration.version(),
+                "recovery": migration.recovery(),
+            })
+            .to_string();
+        }
+        if let Some(crank_registry::RegistryError::Migration(migration)) =
+            cause.downcast_ref::<crank_registry::RegistryError>()
+        {
+            return serde_json::json!({
+                "status": "error",
+                "code": migration.code(),
+                "stage": migration.stage(),
+                "version": migration.version(),
+                "recovery": migration.recovery(),
+            })
+            .to_string();
+        }
+        current = cause.source();
+    }
+    serde_json::json!({
+        "status": "error",
+        "code": "startup_failed",
+        "stage": "startup",
+        "version": null,
+        "recovery": "contact_operator",
+    })
+    .to_string()
+}
+
+async fn main_result() -> Result<(), Box<dyn std::error::Error>> {
+    let effective = parse_process(ProcessKind::McpServer, ConfigSource::from_os()?)?;
+    let config = effective
+        .mcp()
+        .cloned()
+        .ok_or_else(|| io::Error::other("MCP configuration projection is unavailable"))?;
+    preflight_config(&config)?;
+    let observability = init_observability(&config.observability)?;
+    for deprecation in effective.deprecations() {
+        tracing::warn!(
+            name: "config.deprecated",
+            field = deprecation.field,
+            source_class = deprecation.source_class,
+            replacement = deprecation.replacement,
+            removal_window = deprecation.removal_window,
+            "deprecated configuration accepted"
+        );
+    }
    let mut startup_completed = false;
-    let result = run(&observability, &mut startup_completed).await;
+    let result = run(config, &observability, &mut startup_completed).await;
    if result.is_err() {
        capture_critical_error(if startup_completed {
            CriticalErrorCategory::Internal
@@ -38,49 +105,61 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 }

 async fn run(
+    config: McpProcessConfig,
    observability: &ObservabilityLifecycle,
    startup_completed: &mut bool,
 ) -> Result<(), Box<dyn std::error::Error>> {
-    let metrics_config =
-        MetricsConfig::from_env("CRANK_MCP_METRICS_BIND", "127.0.0.1:9465".parse()?)?;
+    let metrics_config = MetricsConfig::new(
+        config.observability.metrics.enabled,
+        config.observability.metrics.bind_addr,
+        config
+            .observability
+            .metrics
+            .bearer_token
+            .as_ref()
+            .map(|token| token.expose_secret().to_owned()),
+    )?;
    let metrics_enabled = metrics_config.enabled();
-    let metrics_server = if metrics_config.enabled() {
+    let pool_config = postgres_pool_config(&config.database)?;
+    let runtime_limits = RuntimeLimits::try_new(
+        config.runtime.max_concurrent_unary,
+        config.runtime.max_concurrent_sessions,
+    )?;
+    let cache_config = runtime_cache_config(&config)?;
+    let cache_stores = RuntimeCacheStores::from_config(&cache_config).await?;
+    let api_rate_limit = RequestRateLimitConfig::new(
+        config.rate_limit.requests_per_second,
+        config.rate_limit.burst,
+    )?;
+    let registry = PostgresRegistry::connect_with_options_and_pool_config(
+        database_options(&config.database)?,
+        pool_config,
+    )
+    .await?;
+    let metrics_server = if metrics_enabled {
        Some(observability.metrics_surface(metrics_config).bind().await?)
    } else {
        None
    };
-
-    let bind_addr = env::var("CRANK_MCP_BIND").unwrap_or_else(|_| "0.0.0.0:3002".into());
-    let base_url = env::var("CRANK_BASE_URL").ok();
-    let refresh_interval = env::var("CRANK_MCP_REFRESH_MS")
-        .ok()
-        .and_then(|value| value.parse::<u64>().ok())
-        .map(Duration::from_millis)
-        .unwrap_or_else(|| Duration::from_secs(5));
-    let socket_addr: SocketAddr = bind_addr.parse()?;
-    let pool_config = PostgresPoolConfig::from_env()?;
-    let runtime_limits = RuntimeLimits::from_env()?;
-    let cache_config = RuntimeCacheConfig::from_env()?;
-    let cache_stores = RuntimeCacheStores::from_config(&cache_config).await?;
-    let api_rate_limit = mcp_api_rate_limit_config_from_env()?;
-    let database_options = database_options_from_env()?;
-    let registry =
-        PostgresRegistry::connect_with_options_and_pool_config(database_options, pool_config)
-            .await?;
    if metrics_enabled {
        spawn_postgres_pool_metrics(registry.pool().clone());
    }
    let session_store = PostgresTransportSessionStore::from_pool(registry.pool().clone()).await?;
-    let secret_crypto = SecretCrypto::new(&env::var("CRANK_MASTER_KEY")?)?;
-    let runtime = crank_runtime::community_from_env()?
+    let secret_crypto = SecretCrypto::new(config.runtime.master_key.expose_secret())?;
+    let outbound_http_policy = crank_runtime::OutboundHttpPolicy::try_new(
+        config.runtime.outbound.allowed_hosts.clone(),
+        config.runtime.outbound.denied_hosts.clone(),
+        config.runtime.outbound.max_response_bytes,
+    )?;
+    let runtime = crank_runtime::community_with_outbound_policy(outbound_http_policy)
        .with_limits(runtime_limits)
        .with_response_cache(cache_stores.response.clone())
        .with_coordination_store(cache_stores.coordination.clone())
        .build();
    let app = build_app_with_background_workers_and_limits(
        registry,
-        refresh_interval,
-        base_url,
+        Duration::from_millis(config.refresh_ms),
+        config.runtime.base_url.clone(),
        secret_crypto,
        runtime,
        if cache_config.backend.is_external() {
@@ -93,7 +172,7 @@ async fn run(
        std::sync::Arc::new(CommunityMachineCredentialVerifier),
        runtime_limits.max_concurrent_sessions,
    );
-    let listener = TcpListener::bind(socket_addr).await?;
+    let listener = TcpListener::bind(config.bind_addr).await?;

    info!(
        name: "mcp.postgres_pool.configured",
@@ -109,11 +188,7 @@ async fn run(
        max_lifetime_ms = pool_config.max_lifetime_ms,
        "postgres pool configured"
    );
-    info!(
-        name: "mcp.server.listening",
-        bind_address = %socket_addr,
-        "mcp-server listening"
-    );
+    info!(name: "mcp.server.listening", bind_address = %config.bind_addr, "mcp-server listening");
    *startup_completed = true;

    if let Some(metrics_server) = metrics_server {
@@ -124,42 +199,176 @@ async fn run(
    } else {
        axum::serve(listener, app).await?;
    }
-
    Ok(())
 }

-fn database_options_from_env() -> Result<PgConnectOptions, Box<dyn std::error::Error>> {
-    if let Ok(database_url) = env::var("CRANK_DATABASE_URL") {
-        return Ok(database_url.parse::<PgConnectOptions>()?);
+fn init_observability(
+    config: &ObservabilitySettings,
+) -> Result<ObservabilityLifecycle, Box<dyn std::error::Error>> {
+    let identity = ServiceIdentity::try_new(
+        "mcp-server",
+        env!("CARGO_PKG_VERSION"),
+        config.environment.clone(),
+    )?;
+    let base = ObservabilityConfig::try_new(
+        identity,
+        config.log_filter.clone(),
+        RedactionLimits::default(),
+    )?;
+    let sentry = SentryConfig::parse(
+        config
+            .sentry_dsn
+            .as_ref()
+            .map(|value| value.expose_secret()),
+    )?;
+    let values = &config.otlp;
+    let otlp = OtlpTraceConfig::from_values(
+        values.endpoint.clone(),
+        values.traces_endpoint.clone(),
+        values.protocol.clone(),
+        values.traces_protocol.clone(),
+        values.timeout.clone(),
+        values.traces_timeout.clone(),
+        values
+            .headers
+            .as_ref()
+            .map(|value| value.expose_secret().to_owned()),
+        values
+            .traces_headers
+            .as_ref()
+            .map(|value| value.expose_secret().to_owned()),
+        values.max_queue_size,
+        values.max_export_batch_size,
+        values.schedule_delay.clone(),
+        values.export_timeout.clone(),
+    )?;
+    Ok(ObservabilityLifecycle::init_with_exporters(
+        base, sentry, otlp,
+    )?)
+}
+
+fn preflight_config(config: &McpProcessConfig) -> Result<(), crank_config::ConfigError> {
+    let invalid = |field| crank_config::ConfigError::single(DiagnosticCode::InvalidType, field);
+    database_options(&config.database).map_err(|_| invalid("database.source"))?;
+    postgres_pool_config(&config.database).map_err(|_| invalid("database.pool"))?;
+    MetricsConfig::new(
+        config.observability.metrics.enabled,
+        config.observability.metrics.bind_addr,
+        config
+            .observability
+            .metrics
+            .bearer_token
+            .as_ref()
+            .map(|v| v.expose_secret().to_owned()),
+    )
+    .map_err(|_| invalid("observability.metrics"))?;
+    RuntimeLimits::try_new(
+        config.runtime.max_concurrent_unary,
+        config.runtime.max_concurrent_sessions,
+    )
+    .map_err(|_| invalid("runtime.limits"))?;
+    runtime_cache_config(config).map_err(|_| invalid("cache"))?;
+    RequestRateLimitConfig::new(
+        config.rate_limit.requests_per_second,
+        config.rate_limit.burst,
+    )
+    .map_err(|_| invalid("mcp.rate_limit"))?;
+    SecretCrypto::new(config.runtime.master_key.expose_secret())
+        .map_err(|_| invalid("runtime.master_key"))?;
+    crank_runtime::OutboundHttpPolicy::try_new(
+        config.runtime.outbound.allowed_hosts.clone(),
+        config.runtime.outbound.denied_hosts.clone(),
+        config.runtime.outbound.max_response_bytes,
+    )
+    .map_err(|_| invalid("runtime.outbound"))?;
+    let identity = ServiceIdentity::try_new(
+        "mcp-server",
+        env!("CARGO_PKG_VERSION"),
+        config.observability.environment.clone(),
+    )
+    .map_err(|_| invalid("observability.environment"))?;
+    ObservabilityConfig::try_new(
+        identity,
+        config.observability.log_filter.clone(),
+        RedactionLimits::default(),
+    )
+    .map_err(|_| invalid("observability.log_filter"))?;
+    SentryConfig::parse(
+        config
+            .observability
+            .sentry_dsn
+            .as_ref()
+            .map(|v| v.expose_secret()),
+    )
+    .map_err(|_| invalid("observability.sentry_dsn"))?;
+    let values = &config.observability.otlp;
+    OtlpTraceConfig::from_values(
+        values.endpoint.clone(),
+        values.traces_endpoint.clone(),
+        values.protocol.clone(),
+        values.traces_protocol.clone(),
+        values.timeout.clone(),
+        values.traces_timeout.clone(),
+        values
+            .headers
+            .as_ref()
+            .map(|v| v.expose_secret().to_owned()),
+        values
+            .traces_headers
+            .as_ref()
+            .map(|v| v.expose_secret().to_owned()),
+        values.max_queue_size,
+        values.max_export_batch_size,
+        values.schedule_delay.clone(),
+        values.export_timeout.clone(),
+    )
+    .map_err(|_| invalid("observability.otlp"))?;
+    Ok(())
+}
+
+fn postgres_pool_config(
+    config: &DatabaseSettings,
+) -> Result<PostgresPoolConfig, crank_registry::PostgresPoolConfigError> {
+    PostgresPoolConfig::try_new(
+        config.pool.max_connections,
+        config.pool.min_connections,
+        config.pool.acquire_timeout_ms,
+        config.pool.idle_timeout_ms,
+        config.pool.max_lifetime_ms,
+    )
+}
+
+fn database_options(
+    config: &DatabaseSettings,
+) -> Result<PgConnectOptions, Box<dyn std::error::Error>> {
+    if let Some(url) = &config.url {
+        return url
+            .expose_secret()
+            .parse::<PgConnectOptions>()
+            .map_err(|_| io::Error::other("database URL is invalid").into());
    }
-
-    let host = env::var("POSTGRES_HOST").unwrap_or_else(|_| "postgres".into());
-    let port = env::var("POSTGRES_PORT")
-        .ok()
-        .and_then(|value| value.parse::<u16>().ok())
-        .unwrap_or(5432);
-    let database = env::var("POSTGRES_DB").unwrap_or_else(|_| "crank".into());
-    let username = env::var("POSTGRES_USER").unwrap_or_else(|_| "crank".into());
-    let password = env::var("POSTGRES_PASSWORD").unwrap_or_else(|_| "crank".into());
-
    Ok(PgConnectOptions::new()
-        .host(&host)
-        .port(port)
-        .database(&database)
-        .username(&username)
-        .password(&password))
+        .host(&config.host)
+        .port(config.port)
+        .database(&config.database)
+        .username(&config.username)
+        .password(config.password.expose_secret()))
 }

-fn mcp_api_rate_limit_config_from_env() -> Result<RequestRateLimitConfig, Box<dyn std::error::Error>>
-{
-    let requests_per_second = env::var("CRANK_MCP_RATE_LIMIT_RPS")
-        .ok()
-        .and_then(|value| value.parse::<u32>().ok())
-        .unwrap_or(60);
-    let burst = env::var("CRANK_MCP_RATE_LIMIT_BURST")
-        .ok()
-        .and_then(|value| value.parse::<u32>().ok())
-        .unwrap_or(120);
-
-    Ok(RequestRateLimitConfig::new(requests_per_second, burst)?)
+fn runtime_cache_config(
+    config: &McpProcessConfig,
+) -> Result<RuntimeCacheConfig, crank_runtime::RuntimeCacheConfigError> {
+    RuntimeCacheConfig::try_new(
+        match config.runtime.cache.backend {
+            ConfigCacheBackend::Memory => CacheBackend::Memory,
+            ConfigCacheBackend::Valkey => CacheBackend::Valkey,
+            ConfigCacheBackend::Redis => CacheBackend::Redis,
+        },
+        config
+            .runtime
+            .cache
+            .url
+            .as_ref()
+            .map(|value| value.expose_secret().to_owned()),
+    )
 }
@@ -0,0 +1,65 @@
+use std::process::Command;
+
+fn run_with(entries: &[(&str, &str)]) -> String {
+    let mut command = Command::new(env!("CARGO_BIN_EXE_mcp-server"));
+    for field in crank_config::field_registry() {
+        command.env_remove(field.env_name);
+    }
+    command.env("CRANK_MASTER_KEY", "master");
+    for (name, value) in entries {
+        command.env(name, value);
+    }
+    let output = command.output().expect("MCP binary executes");
+    assert!(!output.status.success());
+    let stderr = String::from_utf8(output.stderr).expect("stderr is UTF-8");
+    assert!(!stderr.contains("CANARY_SECRET_VALUE"));
+    assert!(!stderr.contains("connection refused"));
+    assert!(stderr.len() <= 65_536);
+    stderr
+}
+
+#[test]
+fn invalid_config_fails_before_database_or_listener_side_effects() {
+    for (entries, code) in [
+        (
+            vec![("CRANK_CONFIG_CANARY_UNKNOWN", "CANARY_SECRET_VALUE")],
+            "config.unknown_field",
+        ),
+        (vec![("CRANK_MCP_REFRESH_MS", "bad")], "config.invalid_type"),
+        (
+            vec![
+                ("CRANK_DATABASE_URL", "postgres://db/crank"),
+                ("POSTGRES_HOST", "other"),
+            ],
+            "config.conflict",
+        ),
+        (vec![("CRANK_LOG_LEVEL", "[")], "config.invalid_type"),
+    ] {
+        let stderr = run_with(&entries);
+        assert!(stderr.contains(code), "{stderr}");
+    }
+}
+
+#[test]
+fn database_driver_failures_are_normalized_and_redacted() {
+    let stderr = run_with(&[(
+        "CRANK_DATABASE_URL",
+        "postgres://CANARY_SECRET_VALUE:CANARY_SECRET_VALUE@127.0.0.1:1/crank",
+    )]);
+    assert!(stderr.contains("startup_failed"), "{stderr}");
+}
+
+#[tokio::test]
+async fn fresh_database_startup_is_read_only() {
+    let database_url = crank_test_support::postgres_schema_url("mcp_startup_read_only").await;
+    let stderr = run_with(&[("CRANK_DATABASE_URL", &database_url)]);
+    assert!(stderr.contains("schema_missing"), "{stderr}");
+    let pool = sqlx::PgPool::connect(&database_url).await.unwrap();
+    let present: bool = sqlx::query_scalar(
+        "select to_regclass(format('%I.%I', current_schema(), '__crank_core_migrations')) is not null",
+    )
+    .fetch_one(&pool)
+    .await
+    .unwrap();
+    assert!(!present);
+}
@@ -1,6 +1,9 @@
 mod integration {
    mod catalog_access;
    mod common;
+    mod execution_stages;
+    mod jsonrpc_correlation;
+    mod request_context;
    mod tool_search;
    mod transport_protocol;
 }
@@ -466,6 +466,10 @@ pub(super) async fn stream_logs()

 pub(super) async fn test_registry() -> PostgresRegistry {
    let database_url = crank_test_support::postgres_schema_url("test_mcp_server").await;
+    let pool = sqlx::PgPool::connect(&database_url).await.unwrap();
+    crank_registry::MigrationAuthority::apply(&pool)
+        .await
+        .unwrap();
    PostgresRegistry::connect(&database_url).await.unwrap()
 }

@@ -154,6 +154,20 @@ async fn exports_real_tool_stages_without_sensitive_data() {
    .await;

    assert_eq!(call_result.status(), StatusCode::OK);
+    assert_eq!(
+        call_result
+            .headers()
+            .get("x-request-id")
+            .and_then(|value| value.to_str().ok()),
+        Some(REQUEST_ID),
+    );
+    assert_eq!(
+        call_result
+            .headers()
+            .get("x-trace-id")
+            .and_then(|value| value.to_str().ok()),
+        Some(REMOTE_TRACE_ID),
+    );
    let body = to_bytes(call_result.into_body(), 1024 * 1024)
        .await
        .unwrap();
@@ -235,6 +249,16 @@ async fn exports_real_tool_stages_without_sensitive_data() {
    assert!(!runtime.parent_span_id.is_empty());
    assert_eq!(runtime.parent_span_id, root.span_id);

+    let upstream = trace_spans
+        .iter()
+        .find(|span| span.name == "upstream.http")
+        .expect("upstream attempt");
+    assert_eq!(
+        decode_span_id(&traceparent[36..52]).as_slice(),
+        upstream.span_id.as_slice(),
+        "outbound traceparent must identify the actual client attempt span",
+    );
+
    let history = trace_spans
        .iter()
        .find(|span| span.name == "history.write")
@@ -263,6 +287,7 @@ async fn exports_real_tool_stages_without_sensitive_data() {
        .unwrap();
    assert_eq!(logs.len(), 1);
    assert_eq!(logs[0].log.request_id.as_deref(), Some(REQUEST_ID));
+    assert_eq!(logs[0].log.trace_id.as_deref(), Some(REMOTE_TRACE_ID));

    provider.shutdown().unwrap();
 }
@@ -310,6 +335,14 @@ fn decode_trace_id(value: &str) -> [u8; 16] {
    bytes
 }

+fn decode_span_id(value: &str) -> [u8; 8] {
+    let mut bytes = [0_u8; 8];
+    for (index, byte) in bytes.iter_mut().enumerate() {
+        *byte = u8::from_str_radix(&value[index * 2..index * 2 + 2], 16).unwrap();
+    }
+    bytes
+}
+
 fn string_attribute<'a>(span: &'a Span, key: &str) -> Option<&'a str> {
    span.attributes.iter().find_map(|attribute| {
        let value = attribute.value.as_ref()?.value.as_ref()?;
@@ -0,0 +1,73 @@
+use std::time::Duration;
+
+use crank_core::PlatformApiKeyScope;
+use crank_registry::PublishRequest;
+use serde_json::{Value, json};
+use time::{OffsetDateTime, format_description::well_known::Rfc3339};
+
+use super::common::{
+    agent_mcp_url, build_test_app, create_platform_api_key, initialize_session,
+    post_jsonrpc_response, publish_agent_for_operation, spawn_mcp_server, spawn_upstream_server,
+    test_operation, test_registry, test_workspace_id,
+};
+
+#[tokio::test]
+async fn generic_jsonrpc_errors_carry_the_same_safe_response_ids() {
+    let registry = test_registry().await;
+    let upstream_base_url = spawn_upstream_server().await;
+    let operation = test_operation(&upstream_base_url, "crm_error_identity");
+    registry
+        .create_operation(&test_workspace_id(), &operation, Some("alice"))
+        .await
+        .unwrap();
+    registry
+        .publish_operation(PublishRequest {
+            workspace_id: &test_workspace_id(),
+            operation_id: &operation.id,
+            version: 1,
+            published_at: &OffsetDateTime::parse("2026-03-26T10:00:00Z", &Rfc3339).unwrap(),
+            published_by: Some("alice"),
+        })
+        .await
+        .unwrap();
+    publish_agent_for_operation(&registry, &operation, "sales-error-identity").await;
+    let api_key = create_platform_api_key(
+        &registry,
+        "sales-error-identity",
+        "mcp-error-identity",
+        &[PlatformApiKeyScope::Read, PlatformApiKeyScope::Write],
+    )
+    .await;
+    let base_url = spawn_mcp_server(build_test_app(registry, Duration::ZERO, None)).await;
+    let client = reqwest::Client::new();
+    let mcp_url = agent_mcp_url(&base_url, "sales-error-identity");
+    let session = initialize_session(&client, &mcp_url, &api_key).await;
+
+    let response = post_jsonrpc_response(
+        &client,
+        &mcp_url,
+        &api_key,
+        Some(&session),
+        Some("jsonrpc-error-request"),
+        json!({
+            "jsonrpc": "2.0",
+            "id": 91,
+            "method": "unsupported/method",
+            "params": {}
+        }),
+    )
+    .await;
+    let request_id = response.headers()["x-request-id"]
+        .to_str()
+        .unwrap()
+        .to_owned();
+    let trace_id = response.headers()["x-trace-id"]
+        .to_str()
+        .unwrap()
+        .to_owned();
+    let payload = response.json::<Value>().await.unwrap();
+
+    assert_eq!(request_id, "jsonrpc-error-request");
+    assert_eq!(payload["error"]["data"]["request_id"], request_id);
+    assert_eq!(payload["error"]["data"]["trace_id"], trace_id);
+}
@@ -9,7 +9,7 @@ use axum::{
 };
 use opentelemetry::{
    global,
-    trace::{TraceId, TracerProvider as _},
+    trace::{SpanId, TraceId, TracerProvider as _},
 };
 use opentelemetry_sdk::{
    error::OTelSdkResult,
@@ -61,6 +61,7 @@ async fn covers_valid_invalid_and_absent_traceparent_on_mcp_boundary() {

    assert_eq!(valid.status, StatusCode::OK);
    assert_eq!(valid.request_id.as_deref(), Some("request-id-is-separate"));
+    assert_eq!(valid.trace_id.as_deref(), Some(REMOTE_TRACE_ID));
    assert_eq!(invalid.status, StatusCode::OK);
    assert_eq!(absent.status, StatusCode::OK);
    assert!(valid.traceparent_response.is_none());
@@ -80,6 +81,41 @@ async fn covers_valid_invalid_and_absent_traceparent_on_mcp_boundary() {
    assert_ne!(trace_ids[2], trace_ids[0]);
    assert_ne!(trace_ids[1], trace_ids[2]);
    assert!(!trace_ids.contains(&TraceId::INVALID));
+    let request_spans = exported
+        .lock()
+        .unwrap()
+        .iter()
+        .filter(|span| span.name.as_ref() == "mcp.request")
+        .cloned()
+        .collect::<Vec<_>>();
+    assert_eq!(
+        request_spans[0].parent_span_id.to_string(),
+        "b7ad6b7169203331"
+    );
+    assert_eq!(request_spans[1].parent_span_id, SpanId::INVALID);
+    assert_eq!(request_spans[2].parent_span_id, SpanId::INVALID);
+    provider.shutdown().unwrap();
+}
+
+#[tokio::test(flavor = "current_thread")]
+async fn sampling_off_still_returns_a_local_trace_identity() {
+    let _tracing_test_guard = TRACING_TEST_LOCK.lock().await;
+    global::set_text_map_propagator(TraceContextPropagator::new());
+    let provider = SdkTracerProvider::builder()
+        .with_sampler(opentelemetry_sdk::trace::Sampler::AlwaysOff)
+        .build();
+    let tracer = provider.tracer("mcp-request-context-sampling-off-test");
+    let subscriber =
+        tracing_subscriber::registry().with(tracing_opentelemetry::layer().with_tracer(tracer));
+    let app = build_test_app(test_registry().await, Duration::ZERO, None);
+
+    let response = send_health(app, None, None)
+        .with_subscriber(subscriber)
+        .await;
+
+    let trace_id = response.trace_id.expect("local trace id");
+    assert_eq!(trace_id.len(), 32);
+    assert_ne!(trace_id, "00000000000000000000000000000000");
    provider.shutdown().unwrap();
 }

@@ -98,6 +134,14 @@ async fn replaces_multiple_request_id_headers_with_one_uuid_v7() {
        "x-request-id",
        HeaderValue::from_static("second-request-id"),
    );
+    request.headers_mut().append(
+        "traceparent",
+        HeaderValue::from_static("00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"),
+    );
+    request.headers_mut().append(
+        "traceparent",
+        HeaderValue::from_static("00-1af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"),
+    );

    let response = app
        .oneshot(request)
@@ -112,6 +156,9 @@ async fn replaces_multiple_request_id_headers_with_one_uuid_v7() {
        uuid::Uuid::parse_str(generated).unwrap().get_version(),
        Some(uuid::Version::SortRand)
    );
+    let trace_id = response.headers()["x-trace-id"].to_str().unwrap();
+    assert_ne!(trace_id, "0af7651916cd43dd8448eb211c80319c");
+    assert_ne!(trace_id, "1af7651916cd43dd8448eb211c80319c");
 }

 async fn send_health(
@@ -143,6 +190,11 @@ async fn send_health(
            .get("traceparent")
            .and_then(|value| value.to_str().ok())
            .map(str::to_owned),
+        trace_id: response
+            .headers()
+            .get("x-trace-id")
+            .and_then(|value| value.to_str().ok())
+            .map(str::to_owned),
    }
 }

@@ -150,6 +202,7 @@ struct ProbeResponse {
    status: StatusCode,
    request_id: Option<String>,
    traceparent_response: Option<String>,
+    trace_id: Option<String>,
 }

 #[derive(Clone, Debug)]
@@ -322,6 +322,10 @@ async fn preserves_request_id_for_tool_call_invocations() {
        response.headers()["x-request-id"].to_str().unwrap(),
        "req_test_123"
    );
+    let trace_id = response.headers()["x-trace-id"]
+        .to_str()
+        .unwrap()
+        .to_owned();
    let call_result = response.json::<Value>().await.unwrap();
    assert_eq!(call_result["result"]["isError"], false);

@@ -341,6 +345,7 @@ async fn preserves_request_id_for_tool_call_invocations() {

    assert_eq!(logs.len(), 1);
    assert_eq!(logs[0].log.request_id.as_deref(), Some("req_test_123"));
+    assert_eq!(logs[0].log.trace_id.as_deref(), Some(trace_id.as_str()));
 }

 #[tokio::test]
@@ -408,6 +413,13 @@ async fn generates_request_id_for_tool_call_responses_and_logs() {
        .to_str()
        .unwrap()
        .to_owned();
+    let trace_id = response
+        .headers()
+        .get("x-trace-id")
+        .unwrap()
+        .to_str()
+        .unwrap()
+        .to_owned();
    assert_eq!(
        uuid::Uuid::parse_str(&request_id).unwrap().get_version(),
        Some(Version::SortRand)
@@ -432,6 +444,7 @@ async fn generates_request_id_for_tool_call_responses_and_logs() {

    assert_eq!(logs.len(), 1);
    assert_eq!(logs[0].log.request_id.as_deref(), Some(request_id.as_str()));
+    assert_eq!(logs[0].log.trace_id.as_deref(), Some(trace_id.as_str()));
 }

 #[tokio::test(flavor = "current_thread")]
@@ -8,6 +8,18 @@
    }, extra || {});
  }

+  function attachCorrelation(error, response) {
+    var requestId = response.headers.get('x-request-id');
+    var traceId = response.headers.get('x-trace-id');
+    if (requestId && requestId.length <= 128 && /^[!-~]+$/.test(requestId) && requestId.indexOf(',') === -1 && requestId.indexOf(';') === -1) {
+      error.requestId = requestId;
+    }
+    if (traceId && /^[0-9a-f]{32}$/.test(traceId) && traceId !== '00000000000000000000000000000000') {
+      error.traceId = traceId;
+    }
+    return error;
+  }
+
  async function request(path, options) {
    var response = await fetch(path, Object.assign({
      credentials: 'same-origin',
@@ -42,11 +54,11 @@
      var error = new Error(message);
      error.status = response.status;
      error.payload = payload;
-      throw error;
+      throw attachCorrelation(error, response);
    }

    if (text && payload === null) {
-      throw new Error('Backend returned a non-JSON response');
+      throw attachCorrelation(new Error('Backend returned a non-JSON response'), response);
    }

    return payload;
@@ -81,7 +93,7 @@
      var error = new Error(message);
      error.status = response.status;
      error.payload = payload;
-      throw error;
+      throw attachCorrelation(error, response);
    }

    return text;
@@ -29,6 +29,10 @@ module.exports = defineConfig({
      url: `${baseURL}/login`,
      timeout: 600_000,
      reuseExistingServer: false,
+      gracefulShutdown: {
+        signal: 'SIGTERM',
+        timeout: 10_000,
+      },
    },
  projects: [
    {
@@ -67,7 +67,8 @@ cleanup() {
  kill_port_processes "$MCP_PORT"
 }

-trap cleanup EXIT INT TERM
+trap cleanup EXIT
+trap 'exit 130' INT TERM

 cleanup

@@ -131,7 +132,13 @@ mkdir -p "$CRANK_STORAGE_ROOT"

 (
  cd "$ROOT_DIR"
-  cargo run -p admin-api >"$LOG_DIR/admin-api.log" 2>&1
+  cargo run -p admin-api --bin crank-migrate -- apply >"$LOG_DIR/migrate.log" 2>&1
+)
+
+(
+  cd "$ROOT_DIR"
+  exec env -u CRANK_MCP_BIND -u CRANK_MCP_REFRESH_MS \
+    cargo run -p admin-api --bin admin-api >"$LOG_DIR/admin-api.log" 2>&1
 ) &
 echo $! > "$TMP_DIR/admin-api.pid"

@@ -141,6 +148,10 @@ done

 (
  cd "$ROOT_DIR"
+  exec env -u CRANK_ADMIN_BIND -u CRANK_STORAGE_ROOT -u CRANK_SESSION_SECRET \
+    -u CRANK_PASSWORD_PEPPER -u CRANK_SESSION_TTL_HOURS \
+    -u CRANK_BOOTSTRAP_ADMIN_EMAIL -u CRANK_BOOTSTRAP_ADMIN_PASSWORD \
+    -u CRANK_BOOTSTRAP_ADMIN_DISPLAY_NAME -u CRANK_DEMO_SEED \
    cargo run -p mcp-server >"$LOG_DIR/mcp-server.log" 2>&1
 ) &
 echo $! > "$TMP_DIR/mcp-server.pid"
@@ -151,7 +162,7 @@ done

 (
  cd "$ROOT_DIR/apps/ui"
-  node scripts/playwright-ui-server.js >"$LOG_DIR/ui-server.log" 2>&1
+  exec node scripts/playwright-ui-server.js >"$LOG_DIR/ui-server.log" 2>&1
 ) &
 echo $! > "$TMP_DIR/ui-server.pid"

@@ -28,3 +28,47 @@ test('secrets page exposes stable secret management hooks', async ({ page }) =>
  await expect(page.locator('[data-testid="secret-submit-button"]')).toBeVisible();
  await expect(page.locator('html')).toHaveAttribute('data-crank-bootstrap-state', 'ready');
 });
+
+test('API errors retain only bounded canonical support identities', async ({ page }) => {
+  await login(page);
+  await page.route('**/api/admin/workspaces/correlation-*/operations', async (route) => {
+    var hostile = route.request().url().includes('correlation-hostile');
+    await route.fulfill({
+      status: 503,
+      contentType: 'application/json',
+      headers: hostile
+        ? { 'x-request-id': 'reflected;attacker', 'x-trace-id': 'NOT-A-TRACE' }
+        : {
+            'x-request-id': '01J5SAFELOCALREQUEST',
+            'x-trace-id': '0123456789abcdef0123456789abcdef',
+          },
+      body: JSON.stringify({ error: { message: 'safe failure' } }),
+    });
+  });
+
+  var safe = await page.evaluate(async () => {
+    try {
+      await window.CrankApi.listOperations('correlation-safe');
+      return null;
+    } catch (error) {
+      return { requestId: error.requestId, traceId: error.traceId };
+    }
+  });
+  expect(safe).toEqual({
+    requestId: '01J5SAFELOCALREQUEST',
+    traceId: '0123456789abcdef0123456789abcdef',
+  });
+
+  var hostile = await page.evaluate(async () => {
+    try {
+      await window.CrankApi.listOperations('correlation-hostile');
+      return null;
+    } catch (error) {
+      return {
+        hasRequestId: Object.prototype.hasOwnProperty.call(error, 'requestId'),
+        hasTraceId: Object.prototype.hasOwnProperty.call(error, 'traceId'),
+      };
+    }
+  });
+  expect(hostile).toEqual({ hasRequestId: false, hasTraceId: false });
+});
@@ -1,16 +1,20 @@
 use std::{
    collections::BTreeMap,
-    env, io,
+    io,
    net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr},
    sync::Arc,
    time::Duration,
 };

-use crank_core::{HttpMethod, RestTarget};
+use crank_core::{HttpMethod, RestTarget, RuntimeRequestContext};
 use crank_metrics::{UpstreamOperationKind, UpstreamOutcome, UpstreamRequestMetrics};
 use crank_trace::{ErrorCategory, Stage, StageOutcome};
 use futures_util::StreamExt;
-use opentelemetry::{global, propagation::Injector, trace::TraceContextExt};
+use opentelemetry::{
+    Context, global,
+    propagation::Injector,
+    trace::{SpanContext, SpanId, TraceContextExt, TraceFlags, TraceId, TraceState},
+};
 use reqwest::{
    Client,
    dns::{Addrs, Name, Resolve, Resolving},
@@ -49,10 +53,6 @@ impl RestAdapter {
        Self::with_policy(OutboundHttpPolicy::default())
    }

-    pub fn from_env() -> Result<Self, RestAdapterError> {
-        Ok(Self::with_policy(OutboundHttpPolicy::from_env()?))
-    }
-
    pub fn with_policy(policy: OutboundHttpPolicy) -> Self {
        let resolver = Arc::new(PolicyDnsResolver {
            policy: policy.clone(),
@@ -73,7 +73,23 @@ impl RestAdapter {
        request: &RestRequest,
    ) -> Result<RestResponse, RestAdapterError> {
        let request_metrics = UpstreamRequestMetrics::start(UpstreamOperationKind::Rest);
-        let result = self.execute_inner(target, request).await;
+        let result = self.execute_inner(target, request, None).await;
+        let outcome = match &result {
+            Ok(_) => UpstreamOutcome::Success,
+            Err(error) => upstream_outcome(error),
+        };
+        request_metrics.complete(outcome);
+        result
+    }
+
+    pub(crate) async fn execute_with_context(
+        &self,
+        target: &RestTarget,
+        request: &RestRequest,
+        context: &RuntimeRequestContext,
+    ) -> Result<RestResponse, RestAdapterError> {
+        let request_metrics = UpstreamRequestMetrics::start(UpstreamOperationKind::Rest);
+        let result = self.execute_inner(target, request, Some(context)).await;
        let outcome = match &result {
            Ok(_) => UpstreamOutcome::Success,
            Err(error) => upstream_outcome(error),
@@ -86,11 +102,33 @@ impl RestAdapter {
        &self,
        target: &RestTarget,
        request: &RestRequest,
+        trusted_context: Option<&RuntimeRequestContext>,
    ) -> Result<RestResponse, RestAdapterError> {
+        let upstream_span = Stage::UpstreamHttp.span();
+        if let Some(context) = trusted_context {
+            set_span_parent_from_traceparent(&upstream_span, context.trace_context.traceparent());
+        }
+        let result = async {
            let url = build_url(target, request)?;
            self.policy.validate_url(&url)?;
            let mut headers = build_headers(target, request)?;
+            if let Some(context) = trusted_context {
+                for (name, value) in context.outbound_headers() {
+                    let (Ok(name), Ok(value)) =
+                        (HeaderName::try_from(name), HeaderValue::try_from(value))
+                    else {
+                        continue;
+                    };
+                    headers.insert(name, value);
+                }
+            }
            apply_current_trace_context(&mut headers);
+            if !headers.contains_key("traceparent")
+                && let Some(context) = trusted_context
+                && let Ok(value) = HeaderValue::from_str(context.trace_context.traceparent())
+            {
+                headers.insert("traceparent", value);
+            }
            let client =
                self.client
                    .as_ref()
@@ -106,8 +144,6 @@ impl RestAdapter {
                builder = builder.json(body);
            }

-        let upstream_span = Stage::UpstreamHttp.span();
-        let result = async {
            let response = builder.send().await?;
            let status = response.status();
            let headers = normalize_headers(response.headers());
@@ -174,32 +210,19 @@ impl Default for OutboundHttpPolicy {
 }

 impl OutboundHttpPolicy {
-    pub fn from_env() -> Result<Self, RestAdapterError> {
-        let max_response_bytes = match env::var("CRANK_OUTBOUND_MAX_RESPONSE_BYTES") {
-            Ok(value) => {
-                value
-                    .parse::<usize>()
-                    .map_err(|_| RestAdapterError::InvalidConfiguration {
-                        details: "CRANK_OUTBOUND_MAX_RESPONSE_BYTES must be a positive integer"
-                            .to_owned(),
-                    })?
-            }
-            Err(env::VarError::NotPresent) => DEFAULT_MAX_RESPONSE_BYTES,
-            Err(error) => {
-                return Err(RestAdapterError::InvalidConfiguration {
-                    details: error.to_string(),
-                });
-            }
-        };
+    pub fn try_new(
+        allowed_hosts: Vec<String>,
+        denied_hosts: Vec<String>,
+        max_response_bytes: usize,
+    ) -> Result<Self, RestAdapterError> {
        if max_response_bytes == 0 {
            return Err(RestAdapterError::InvalidConfiguration {
-                details: "CRANK_OUTBOUND_MAX_RESPONSE_BYTES must be greater than zero".to_owned(),
+                details: "outbound response limit must be greater than zero".to_owned(),
            });
        }
-
        Ok(Self {
-            allowed_hosts: host_patterns_from_env("CRANK_OUTBOUND_ALLOWED_HOSTS")?,
-            denied_hosts: host_patterns_from_env("CRANK_OUTBOUND_DENIED_HOSTS")?,
+            allowed_hosts: validate_host_patterns(allowed_hosts)?,
+            denied_hosts: validate_host_patterns(denied_hosts)?,
            max_response_bytes,
        })
    }
@@ -308,20 +331,11 @@ fn boxed_io_error(message: String) -> Box<dyn std::error::Error + Send + Sync> {
    Box::new(io::Error::new(io::ErrorKind::PermissionDenied, message))
 }

-fn host_patterns_from_env(name: &str) -> Result<Vec<String>, RestAdapterError> {
-    let value = match env::var(name) {
-        Ok(value) => value,
-        Err(env::VarError::NotPresent) => return Ok(Vec::new()),
-        Err(error) => {
-            return Err(RestAdapterError::InvalidConfiguration {
-                details: error.to_string(),
-            });
-        }
-    };
-    value
-        .split(',')
-        .map(str::trim)
-        .filter(|value| !value.is_empty())
+fn validate_host_patterns(
+    values: impl IntoIterator<Item = String>,
+) -> Result<Vec<String>, RestAdapterError> {
+    values
+        .into_iter()
        .map(|value| {
            let wildcard = value.starts_with("*.");
            let normalized = normalize_host(value.trim_start_matches("*."));
@@ -332,7 +346,7 @@ fn host_patterns_from_env(name: &str) -> Result<Vec<String>, RestAdapterError> {
                || (wildcard && normalized.parse::<IpAddr>().is_ok())
            {
                return Err(RestAdapterError::InvalidConfiguration {
-                    details: format!("{name} contains an invalid host pattern: {value}"),
+                    details: "outbound host pattern is invalid".to_owned(),
                });
            }
            Ok(if wildcard {
@@ -465,7 +479,7 @@ fn insert_header(headers: &mut HeaderMap, name: &str, value: &str) -> Result<(),
        HeaderName::try_from(name).map_err(|_| RestAdapterError::InvalidHeaderName {
            header: name.to_owned(),
        })?;
-    if is_trace_propagation_header(&header_name) {
+    if is_reserved_correlation_header(&header_name) {
        return Ok(());
    }
    let header_value =
@@ -477,12 +491,53 @@ fn insert_header(headers: &mut HeaderMap, name: &str, value: &str) -> Result<(),
    Ok(())
 }

-fn is_trace_propagation_header(name: &HeaderName) -> bool {
-    matches!(name.as_str(), "traceparent" | "tracestate" | "baggage")
+fn is_reserved_correlation_header(name: &HeaderName) -> bool {
+    matches!(
+        name.as_str(),
+        "traceparent"
+            | "tracestate"
+            | "baggage"
+            | "x-request-id"
+            | "x-trace-id"
+            | "x-correlation-id"
+    )
+}
+
+fn set_span_parent_from_traceparent(span: &Span, traceparent: &str) -> bool {
+    let mut parts = traceparent.split('-');
+    let (Some("00"), Some(trace_id), Some(parent_id), Some(flags), None) = (
+        parts.next(),
+        parts.next(),
+        parts.next(),
+        parts.next(),
+        parts.next(),
+    ) else {
+        return false;
+    };
+    let (Ok(trace_id), Ok(parent_id)) = (TraceId::from_hex(trace_id), SpanId::from_hex(parent_id))
+    else {
+        return false;
+    };
+    let trace_flags = if flags == "01" {
+        TraceFlags::SAMPLED
+    } else if flags == "00" {
+        TraceFlags::default()
+    } else {
+        return false;
+    };
+    let parent = SpanContext::new(
+        trace_id,
+        parent_id,
+        trace_flags,
+        true,
+        TraceState::default(),
+    );
+    span.set_parent(Context::new().with_remote_span_context(parent))
+        .is_ok()
 }

 fn apply_current_trace_context(headers: &mut HeaderMap) {
-    for header in ["traceparent", "tracestate", "baggage"] {
+    for header in ["tracestate", "baggage"] {
        headers.remove(header);
    }

@@ -490,6 +545,7 @@ fn apply_current_trace_context(headers: &mut HeaderMap) {
    if !context.span().span_context().is_valid() {
        return;
    }
+    headers.remove("traceparent");
    global::get_text_map_propagator(|propagator| {
        propagator.inject_context(&context, &mut ReqwestHeaderInjector(headers));
    });
@@ -29,16 +29,14 @@ impl ProtocolAdapter for RestAdapter {
        context: &RuntimeRequestContext,
    ) -> Result<AdapterResponse, ProtocolAdapterError> {
        let target = rest_target(target)?;
-        let mut headers = prepared.headers.clone();
-        headers.extend(context.outbound_headers());
        let request = RestRequest {
            path_params: prepared.path_params.clone(),
            query_params: prepared.query_params.clone(),
-            headers,
+            headers: prepared.headers.clone(),
            body: prepared.body.clone(),
            timeout_ms: prepared.timeout_ms,
        };
-        let response = self.execute(target, &request).await?;
+        let response = self.execute_with_context(target, &request, context).await?;

        Ok(AdapterResponse {
            status_code: response.status_code,
@@ -48,7 +48,7 @@ async fn executes_rest_request_and_normalizes_json_response() {
        json!({
            "id": "42",
            "query": "true",
-            "trace": "trace-123",
+            "trace": "",
            "static": "static",
            "payload": { "name": "Ada" }
        })
@@ -69,6 +69,7 @@ async fn protocol_context_overrides_mapped_correlation_headers() {
                "x-correlation-id".to_owned(),
                "static-correlation".to_owned(),
            ),
+            ("x-trace-id".to_owned(), "static-trace".to_owned()),
        ]),
    });
    let prepared = PreparedRequest {
@@ -79,12 +80,17 @@ async fn protocol_context_overrides_mapped_correlation_headers() {
                "x-correlation-id".to_owned(),
                "mapped-correlation".to_owned(),
            ),
+            ("x-trace-id".to_owned(), "mapped-trace".to_owned()),
        ]),
        body: Some(json!({ "name": "Ada" })),
        timeout_ms: 1_000,
        ..PreparedRequest::default()
    };
-    let context = RuntimeRequestContext::new("req-runtime", "corr-runtime");
+    let context = RuntimeRequestContext::new(
+        crank_core::RequestId::resolve(Some("req-runtime")),
+        crank_core::TraceContext::parse("00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01")
+            .unwrap(),
+    );

    let response = adapter
        .invoke_unary(&target, &prepared, &context)
@@ -92,7 +98,12 @@ async fn protocol_context_overrides_mapped_correlation_headers() {
        .unwrap();

    assert_eq!(response.body["request_id"], "req-runtime");
-    assert_eq!(response.body["correlation_id"], "corr-runtime");
+    assert_eq!(response.body["correlation_id"], "req-runtime");
+    assert_eq!(response.body["trace"], "0af7651916cd43dd8448eb211c80319c");
+    assert_eq!(
+        &response.body["traceparent"].as_str().unwrap()[3..35],
+        "0af7651916cd43dd8448eb211c80319c"
+    );
 }

 #[tokio::test(flavor = "current_thread")]
@@ -14,7 +14,7 @@ use axum::{
 };
 use crank_core::{
    ApprovalRequest, ApprovalRequestId, ApprovalRequestStatus, AuthProfile, CoordinationStateStore,
-    InvocationLevel, InvocationSource, InvocationStatus, OperationApprovalMode,
+    CorrelationContext, InvocationLevel, InvocationSource, InvocationStatus, OperationApprovalMode,
    PlatformApiKeyScope, SecretId,
 };
 use crank_registry::{
@@ -64,10 +64,12 @@ use crate::{
 mod invocation_history;
 mod metrics;
 mod stages;
+mod tool_resolution;
 use self::metrics::{ActiveStreamGuard, McpRequestMetrics};
 use self::stages::{
    enforce_traced_rate_limit, require_traced_approval_access, require_traced_machine_access,
 };
+pub(super) use self::tool_resolution::{resolve_generated_tool, runtime_operation};
 #[cfg(test)]
 use invocation_history::observe_invocation_history_outcome;
 pub(super) use invocation_history::{InvocationRecord, persist_invocation};
@@ -298,13 +300,13 @@ async fn readiness(State(state): State<Arc<AppState>>) -> Response {
            "checks": { "postgres": "ready" }
        }))
        .into_response(),
-        Err(error) => (
+        Err(_) => (
            StatusCode::SERVICE_UNAVAILABLE,
            Json(json!({
                "service": "mcp-server",
                "status": "not_ready",
                "checks": { "postgres": "not_ready" },
-                "error": error.to_string()
+                "error": "database is unavailable"
            })),
        )
            .into_response(),
@@ -363,7 +365,7 @@ async fn approve_request(
        payload,
        PlatformApiKeyScope::Approve,
        ApprovalRequestStatus::Approved,
-        Some(request_context.request_id),
+        Some(request_context.correlation),
    )
    .await
 }
@@ -425,7 +427,7 @@ async fn decide_approval_request(
    payload: ApprovalDecisionPayload,
    required_scope: PlatformApiKeyScope,
    status: ApprovalRequestStatus,
-    execution_request_id: Option<String>,
+    execution_correlation: Option<CorrelationContext>,
 ) -> Response {
    let agent_path = AgentRoutePath {
        workspace_slug: path.workspace_slug,
@@ -496,7 +498,7 @@ async fn decide_approval_request(
                &state,
                &agent_path,
                claimed,
-                execution_request_id.as_deref(),
+                execution_correlation.as_ref(),
            )
            .await
            {
@@ -719,11 +721,12 @@ async fn mcp_post(
            let mut request_metrics = McpRequestMetrics::invalid();
            let response = rejection.into_response();
            request_metrics.complete(&response);
-            return with_request_id_header(response, &request_context.request_id);
+            return with_request_id_header(response, request_context.request_id());
        }
    };
    let mut request_metrics = McpRequestMetrics::new(&message);
-    let transport_request_id = request_context.request_id;
+    let transport_correlation = request_context.correlation;
+    let transport_request_id = transport_correlation.request_id().to_string();
    info!(
        name: "mcp.request.received",
        request_id = %transport_request_id,
@@ -733,7 +736,8 @@ async fn mcp_post(
        "mcp request received"
    );

-    let response = mcp_post_response(&path, state, &headers, &message, &transport_request_id).await;
+    let response =
+        mcp_post_response(&path, state, &headers, &message, &transport_correlation).await;
    request_metrics.complete(&response);
    with_request_id_header(response, &transport_request_id)
 }
@@ -743,7 +747,7 @@ async fn mcp_post_response(
    state: Arc<AppState>,
    headers: &HeaderMap,
    message: &Value,
-    transport_request_id: &str,
+    transport_correlation: &CorrelationContext,
 ) -> Response {
    if let Err(status) = validate_origin(&state.allowed_origins, headers) {
        return status.into_response();
@@ -851,10 +855,10 @@ async fn mcp_post_response(
            };
            let tool_call_params: ToolCallParams = match serde_json::from_value(params(message)) {
                Ok(value) => value,
-                Err(error) => {
+                Err(_) => {
                    return transport_response(
                        StatusCode::OK,
-                        jsonrpc_error(request_id(message), -32602, error.to_string()),
+                        jsonrpc_error(request_id(message), -32602, "invalid tool call parameters"),
                        response_mode,
                        None,
                        Some(&session.protocol_version),
@@ -883,7 +887,7 @@ async fn mcp_post_response(
                        &catalog,
                        &tool_call_params.name,
                        arguments,
-                        transport_request_id,
+                        transport_correlation,
                    )
                    .await
                }
@@ -925,8 +929,9 @@ pub(super) async fn handle_tool_call(
    resolved: ResolvedToolCall,
    arguments: Value,
    confirmation_token: Option<String>,
-    transport_request_id: &str,
+    transport_correlation: &CorrelationContext,
 ) -> Response {
+    let transport_request_id = transport_correlation.request_id().as_str();
    if !credential_allows_security_level(credential, resolved.tool.operation.security_level) {
        return tool_error_response(
            message,
@@ -940,6 +945,7 @@ pub(super) async fn handle_tool_call(
                    serialize_security_level(resolved.tool.operation.security_level),
                ),
                transport_request_id,
+                transport_correlation.trace_id().as_str(),
                false,
                Some("Используйте ключ агента с достаточным уровнем доступа."),
            ),
@@ -956,7 +962,7 @@ pub(super) async fn handle_tool_call(
            arguments,
            confirmation_token,
        },
-        transport_request_id,
+        transport_correlation,
    )
    .await
 }
@@ -1076,8 +1082,9 @@ async fn handle_base_tool_call(
    message: &Value,
    response_mode: ResponseMode,
    execution: ToolCallExecution,
-    transport_request_id: &str,
+    transport_correlation: &CorrelationContext,
 ) -> Response {
+    let transport_request_id = transport_correlation.request_id().as_str();
    let tool = execution.tool;
    let arguments = execution.arguments;
    let operation = runtime_operation(&tool);
@@ -1096,7 +1103,7 @@ async fn handle_base_tool_call(
            response_mode,
            &tool,
            &arguments,
-            transport_request_id,
+            transport_correlation,
        )
        .instrument(approval_span.clone())
        .await;
@@ -1116,7 +1123,8 @@ async fn handle_base_tool_call(
        StageOutcome::Allowed.record(&approval_span);
    }

-    let mut runtime_request_context = RuntimeRequestContext::from_request_id(transport_request_id)
+    let mut runtime_request_context =
+        RuntimeRequestContext::from_correlation(transport_correlation)
            .with_response_cache_scope(
                tool.workspace_id.as_str().to_owned(),
                tool.agent_id.as_str().to_owned(),
@@ -1155,6 +1163,7 @@ async fn handle_base_tool_call(
                &tool,
                InvocationRecord {
                    request_id: Some(transport_request_id),
+                    trace_id: Some(transport_correlation.trace_id().as_str()),
                    tool_name: &tool.tool_name,
                    status: InvocationStatus::Ok,
                    level: InvocationLevel::Info,
@@ -1176,10 +1185,11 @@ async fn handle_base_tool_call(
                &tool,
                InvocationRecord {
                    request_id: Some(transport_request_id),
+                    trace_id: Some(transport_correlation.trace_id().as_str()),
                    tool_name: &tool.tool_name,
                    status: InvocationStatus::Error,
                    level: InvocationLevel::Error,
-                    message: &error.to_string(),
+                    message: runtime_error_code(&error),
                    status_code: None,
                    error_kind: Some(runtime_error_code(&error)),
                    duration: started_at.elapsed(),
@@ -1193,7 +1203,11 @@ async fn handle_base_tool_call(
                message,
                response_mode,
                &session.protocol_version,
-                tool_error_contract_from_runtime(&error, transport_request_id),
+                tool_error_contract_from_runtime(
+                    &error,
+                    transport_request_id,
+                    transport_correlation.trace_id().as_str(),
+                ),
            )
        }
    }
@@ -1211,7 +1225,7 @@ async fn maybe_handle_approval_policy(
    response_mode: ResponseMode,
    tool: &PublishedAgentTool,
    arguments: &Value,
-    transport_request_id: &str,
+    transport_correlation: &CorrelationContext,
 ) -> Option<ApprovalPolicyResult> {
    let policy = tool.operation.execution_config.approval_policy.as_ref()?;
    if !policy.required {
@@ -1227,7 +1241,7 @@ async fn maybe_handle_approval_policy(
                response_mode,
                tool,
                arguments,
-                transport_request_id,
+                transport_correlation,
            )
            .await
        }
@@ -1238,7 +1252,7 @@ async fn maybe_handle_approval_policy(
            tool,
            arguments,
            policy.elicitation_message.as_deref(),
-            transport_request_id,
+            transport_correlation,
        )),
    }
 }
@@ -1250,8 +1264,9 @@ async fn maybe_create_custom_pending_approval(
    response_mode: ResponseMode,
    tool: &PublishedAgentTool,
    arguments: &Value,
-    transport_request_id: &str,
+    transport_correlation: &CorrelationContext,
 ) -> Option<ApprovalPolicyResult> {
+    let transport_request_id = transport_correlation.request_id().as_str();
    let policy = tool.operation.execution_config.approval_policy.as_ref()?;

    let approval_id = ApprovalRequestId::new(format!("approval_{}", uuid::Uuid::now_v7().simple()));
@@ -1298,6 +1313,7 @@ async fn maybe_create_custom_pending_approval(
        tool,
        InvocationRecord {
            request_id: Some(transport_request_id),
+            trace_id: Some(transport_correlation.trace_id().as_str()),
            tool_name: &tool.tool_name,
            status: InvocationStatus::Ok,
            level: InvocationLevel::Info,
@@ -1326,8 +1342,9 @@ fn handle_elicitation_approval(
    tool: &PublishedAgentTool,
    arguments: &Value,
    elicitation_message: Option<&str>,
-    transport_request_id: &str,
+    transport_correlation: &CorrelationContext,
 ) -> ApprovalPolicyResult {
+    let transport_request_id = transport_correlation.request_id().as_str();
    if !session.supports_elicitation {
        return ApprovalPolicyResult::Error(tool_error_response(
            message,
@@ -1337,6 +1354,7 @@ fn handle_elicitation_approval(
                "approval_elicitation_not_supported",
                "operation requires MCP Elicitation, but the MCP client did not advertise elicitation capability",
                transport_request_id,
+                transport_correlation.trace_id().as_str(),
                false,
                Some(
                    "Выберите Custom MCP Approval или подключите MCP-клиент с поддержкой elicitation.",
@@ -1375,10 +1393,10 @@ async fn handle_initialize(
 ) -> Response {
    let initialize_params: InitializeParams = match serde_json::from_value(params(message)) {
        Ok(value) => value,
-        Err(error) => {
+        Err(_error) => {
            return transport_response(
                StatusCode::OK,
-                jsonrpc_error(request_id(message), -32602, error.to_string()),
+                jsonrpc_error(request_id(message), -32602, "invalid initialize parameters"),
                response_mode,
                None,
                Some(DEFAULT_PROTOCOL_VERSION),
@@ -1513,10 +1531,10 @@ async fn require_initialized_session(
    Ok(session)
 }

-fn internal_jsonrpc_error(message: &Value, error: impl std::fmt::Display) -> Response {
+fn internal_jsonrpc_error(message: &Value, _error: impl std::fmt::Display) -> Response {
    transport_response(
        StatusCode::INTERNAL_SERVER_ERROR,
-        jsonrpc_error(request_id(message), -32603, error.to_string()),
+        jsonrpc_error(request_id(message), -32603, "internal server error"),
        ResponseMode::Json,
        None,
        Some(DEFAULT_PROTOCOL_VERSION),
@@ -1614,26 +1632,5 @@ fn add_millis(timestamp: OffsetDateTime, millis: u64) -> OffsetDateTime {
    timestamp + delta
 }

-pub(super) fn resolve_generated_tool(
-    tools: &[PublishedAgentTool],
-    tool_name: &str,
-) -> Option<ResolvedToolCall> {
-    for tool in tools {
-        if tool.tool_name == tool_name {
-            return Some(ResolvedToolCall { tool: tool.clone() });
-        }
-    }
-
-    None
-}
-
-pub(super) fn runtime_operation(tool: &PublishedAgentTool) -> RuntimeOperation {
-    let mut operation = RuntimeOperation::from(tool.operation.clone());
-    operation.tool_name = tool.tool_name.clone();
-    operation.tool_description.title = tool.tool_title.clone();
-    operation.tool_description.description = tool.tool_description.clone();
-    operation
-}
-
 #[cfg(test)]
 mod tests;
@@ -15,6 +15,7 @@ use super::AppState;

 pub(crate) struct InvocationRecord<'a> {
    pub(crate) request_id: Option<&'a str>,
+    pub(crate) trace_id: Option<&'a str>,
    pub(crate) tool_name: &'a str,
    pub(crate) status: InvocationStatus,
    pub(crate) level: InvocationLevel,
@@ -42,6 +43,7 @@ pub(crate) async fn persist_invocation(
        tool_name: record.tool_name.to_owned(),
        message: record.message.to_owned(),
        request_id: record.request_id.map(ToOwned::to_owned),
+        trace_id: record.trace_id.map(ToOwned::to_owned),
        status_code: record.status_code,
        duration_ms: u64::try_from(record.duration.as_millis()).unwrap_or(u64::MAX),
        error_kind: record.error_kind.map(ToOwned::to_owned),
@@ -79,6 +81,7 @@ pub(crate) async fn persist_invocation(
    observe_invocation_history_outcome(
        outcome,
        record.request_id,
+        record.trace_id,
        record.status,
        InvocationSource::AgentToolCall,
    );
@@ -88,6 +91,7 @@ pub(crate) async fn persist_invocation(
 pub(super) fn observe_invocation_history_outcome(
    outcome: InvocationHistoryWriteOutcome,
    request_id: Option<&str>,
+    trace_id: Option<&str>,
    status: InvocationStatus,
    source: InvocationSource,
 ) {
@@ -100,6 +104,7 @@ pub(super) fn observe_invocation_history_outcome(
    warn!(
        name: "mcp.invocation_history.lost",
        request_id = request_id.unwrap_or_default(),
+        trace_id = trace_id.unwrap_or_default(),
        source = invocation_source_label(source),
        invocation_status = invocation_status_label(status),
        error_category = loss.category.as_str(),
@@ -37,6 +37,7 @@ async fn tool_error_response_includes_structured_context() {
            "streaming_payload_error",
            "request root must be an object",
            "req-1",
+            "0af7651916cd43dd8448eb211c80319c",
            false,
            Some("Проверьте параметры вызова инструмента."),
        ),
@@ -59,6 +60,7 @@ async fn tool_error_response_includes_structured_context() {
            "message": "request root must be an object",
            "recoverable": false,
            "request_id": "req-1",
+            "trace_id": "0af7651916cd43dd8448eb211c80319c",
            "suggested_action": "Проверьте параметры вызова инструмента."
        })
    );
@@ -146,6 +148,7 @@ fn emits_bounded_history_loss_incident() {
            category: InvocationHistoryLossCategory::Unavailable,
        }),
        Some("req_mcp_dc08"),
+        Some("0af7651916cd43dd8448eb211c80319c"),
        InvocationStatus::Ok,
        crank_core::InvocationSource::AgentToolCall,
    );
@@ -0,0 +1,23 @@
+use crank_registry::PublishedAgentTool;
+use crank_runtime::RuntimeOperation;
+
+use super::ResolvedToolCall;
+
+pub(crate) fn resolve_generated_tool(
+    tools: &[PublishedAgentTool],
+    tool_name: &str,
+) -> Option<ResolvedToolCall> {
+    tools
+        .iter()
+        .find(|tool| tool.tool_name == tool_name)
+        .cloned()
+        .map(|tool| ResolvedToolCall { tool })
+}
+
+pub(crate) fn runtime_operation(tool: &PublishedAgentTool) -> RuntimeOperation {
+    let mut operation = RuntimeOperation::from(tool.operation.clone());
+    operation.tool_name = tool.tool_name.clone();
+    operation.tool_description.title = tool.tool_title.clone();
+    operation.tool_description.description = tool.tool_description.clone();
+    operation
+}
@@ -5,7 +5,7 @@ use axum::{
    response::{IntoResponse, Response},
 };
 use crank_core::{ApprovalRequestStatus, InvocationLevel, InvocationSource, InvocationStatus};
-use crank_observability::RequestId;
+use crank_core::{CorrelationContext, RequestId, TraceContext};
 use crank_registry::{ApprovalRequestRecord, FinishApprovalRequest};
 use crank_runtime::{RuntimeExecutionRequest, RuntimeRequestContext};
 use crank_trace::{DbOperation, ErrorCategory, Stage, StageOutcome, observe_db_query};
@@ -18,7 +18,7 @@ use crate::{
        AgentRoutePath, AppState, InvocationRecord, build_request_preview, persist_invocation,
        resolve_operation_auth, runtime_operation,
    },
-    tool_error::runtime_error_code,
+    tool_error::{runtime_error_code, safe_runtime_error_message},
 };

 const RECOVERY_INTERVAL: std::time::Duration = std::time::Duration::from_secs(5);
@@ -64,7 +64,10 @@ async fn recover_approved_requests(state: &Arc<AppState>) {
            continue;
        };
        let recovery_span = Stage::ApprovalRecovery.span();
-        let result = execute_approved_request(state, &path, approval, None)
+        let trace_context = crank_trace::trace_context_for_span(&recovery_span)
+            .unwrap_or_else(TraceContext::generate);
+        let correlation = CorrelationContext::new(RequestId::generate(), trace_context);
+        let result = execute_approved_request(state, &path, approval, Some(&correlation))
            .instrument(recovery_span.clone())
            .await;
        match &result {
@@ -162,9 +165,12 @@ pub(super) async fn execute_approved_request(
    state: &Arc<AppState>,
    path: &AgentRoutePath,
    approval: ApprovalRequestRecord,
-    request_id: Option<&str>,
+    correlation: Option<&CorrelationContext>,
 ) -> Result<ApprovalRequestRecord, Response> {
-    let request_id = RequestId::resolve(request_id).into_string();
+    let correlation = correlation
+        .cloned()
+        .unwrap_or_else(CorrelationContext::generate);
+    let request_id = correlation.request_id().as_str();
    let tools = state
        .catalog
        .list_tools(&path.workspace_slug, &path.agent_slug)
@@ -184,7 +190,7 @@ pub(super) async fn execute_approved_request(
        &approval.approval.request_payload,
    );
    let started_at = Instant::now();
-    let runtime_request_context = RuntimeRequestContext::from_request_id(request_id.clone())
+    let runtime_request_context = RuntimeRequestContext::from_correlation(&correlation)
        .with_response_cache_scope(
            tool.workspace_id.as_str().to_owned(),
            tool.agent_id.as_str().to_owned(),
@@ -226,7 +232,7 @@ pub(super) async fn execute_approved_request(
                json!({
                    "error": {
                        "code": runtime_error_code(&error),
-                        "message": error.to_string(),
+                        "message": safe_runtime_error_message(&error),
                    }
                }),
                InvocationStatus::Error,
@@ -240,7 +246,8 @@ pub(super) async fn execute_approved_request(
        state,
        &tool,
        InvocationRecord {
-            request_id: Some(&request_id),
+            request_id: Some(request_id),
+            trace_id: Some(correlation.trace_id().as_str()),
            tool_name: &tool.tool_name,
            status: invocation_status,
            level: invocation_level,
@@ -45,16 +45,35 @@ pub fn jsonrpc_result(id: Value, result: Value) -> Value {
 }

 pub fn jsonrpc_error(id: Value, code: i64, message: impl Into<String>) -> Value {
+    let mut error = json!({
+        "code": code,
+        "message": message.into()
+    });
+    let (request_id, trace_id) = crank_observability::current_request_correlation();
+    if request_id.is_some() && trace_id.is_some() {
+        error["data"] = correlated_error_data(json!({}));
+    }
    json!({
        "jsonrpc": "2.0",
        "id": id,
-        "error": {
-            "code": code,
-            "message": message.into()
-        }
+        "error": error
    })
 }

+pub fn correlated_error_data(mut data: Value) -> Value {
+    if !data.is_object() {
+        data = json!({});
+    }
+    let (request_id, trace_id) = crank_observability::current_request_correlation();
+    if let Some(request_id) = request_id {
+        data["request_id"] = Value::String(request_id);
+    }
+    if let Some(trace_id) = trace_id {
+        data["trace_id"] = Value::String(trace_id);
+    }
+    data
+}
+
 pub fn negotiated_protocol_version(requested: &str) -> Option<&'static str> {
    SUPPORTED_PROTOCOL_VERSIONS
        .iter()
@@ -11,7 +11,7 @@ use serde_json::{Value, json};
 use crate::{
    access::{bearer_token, hash_access_secret},
    app::{AgentRoutePath, AppState},
-    jsonrpc::request_id,
+    jsonrpc::{correlated_error_data, request_id},
    transport::{ResponseMode, session_id_from_headers, transport_response},
 };

@@ -39,7 +39,7 @@ pub(super) fn rate_limited_jsonrpc_response(
                "error": {
                    "code": -32603,
                    "message": "rate limit service unavailable",
-                    "data": { "code": "rate_limit_unavailable" }
+                    "data": correlated_error_data(json!({ "code": "rate_limit_unavailable" }))
                }
            }),
            response_mode,
@@ -53,10 +53,10 @@ pub(super) fn rate_limited_jsonrpc_response(
        "error": {
            "code": -32029,
            "message": "request rate limit exceeded",
-            "data": {
+            "data": correlated_error_data(json!({
                "code": "request_rate_limited",
                "retry_after_ms": rejection.retry_after_ms,
-            }
+            }))
        }
    });

@@ -1,33 +1,101 @@
 use axum::{extract::Request, http::HeaderValue, middleware::Next, response::Response};
-use crank_observability::{RequestId, set_remote_trace_parent, with_request_correlation};
+use crank_core::{CorrelationContext, RequestId, TraceContext};
+use crank_observability::{set_remote_trace_parent, with_request_correlation};
 use tracing::{Instrument, info_span};

 use crate::transport::HEADER_X_REQUEST_ID;

+const HEADER_X_TRACE_ID: axum::http::HeaderName = axum::http::HeaderName::from_static("x-trace-id");
+
 #[derive(Clone, Debug)]
 pub(super) struct RequestContext {
-    pub(super) request_id: String,
+    pub(super) correlation: CorrelationContext,
+}
+
+impl RequestContext {
+    pub(super) fn request_id(&self) -> &str {
+        self.correlation.request_id().as_str()
+    }
 }

 pub(super) async fn apply_request_context(mut request: Request, next: Next) -> Response {
-    let request_id = RequestId::resolve_from_headers(request.headers()).into_string();
-    let context = RequestContext {
-        request_id: request_id.clone(),
-    };
+    let (request_id, remote_parent) = resolve_correlation(request.headers());
    let span = info_span!(
        target: "crank::trace",
        "mcp.request",
        request_id = %request_id,
+        trace_id = tracing::field::Empty,
    );
-    set_remote_trace_parent(&span, request.headers());
-    request.extensions_mut().insert(context);
+    if let Some(remote_parent) = remote_parent.as_ref() {
+        set_canonical_parent(&span, remote_parent);
+    }
+    let trace_context = crank_trace::trace_context_for_span(&span).unwrap_or_else(|| {
+        remote_parent
+            .as_ref()
+            .map_or_else(TraceContext::generate, TraceContext::continue_local)
+    });
+    span.record("trace_id", trace_context.trace_id().as_str());
+    let context = RequestContext {
+        correlation: CorrelationContext::new(request_id, trace_context),
+    };
+    request.extensions_mut().insert(context.clone());

-    with_request_correlation(request_id.clone(), async move {
+    with_request_correlation(
+        context.correlation.request_id().to_string(),
+        context.correlation.trace_id().to_string(),
+        async move {
            let mut response = next.run(request).instrument(span).await;
-        if let Ok(value) = HeaderValue::from_str(&request_id) {
+            if let Ok(value) = HeaderValue::from_str(context.correlation.request_id().as_str()) {
                response.headers_mut().insert(HEADER_X_REQUEST_ID, value);
            }
+            if let Ok(value) = HeaderValue::from_str(context.correlation.trace_id().as_str()) {
+                response.headers_mut().insert(HEADER_X_TRACE_ID, value);
+            }
            response
-    })
+        },
+    )
    .await
 }
+
+fn resolve_correlation(headers: &axum::http::HeaderMap) -> (RequestId, Option<TraceContext>) {
+    let _tracestate_accepted = one_auxiliary_header_within_budget(
+        headers,
+        "tracestate",
+        TraceContext::tracestate_within_budget,
+    );
+    let _baggage_accepted =
+        one_auxiliary_header_within_budget(headers, "baggage", TraceContext::baggage_within_budget);
+    let mut request_ids = headers.get_all(HEADER_X_REQUEST_ID).iter();
+    let request_id = request_ids.next().and_then(|value| value.to_str().ok());
+    let request_id = if request_ids.next().is_some() {
+        RequestId::generate()
+    } else {
+        RequestId::resolve(request_id)
+    };
+    let mut traceparents = headers.get_all("traceparent").iter();
+    let traceparent = traceparents.next().and_then(|value| value.to_str().ok());
+    let remote_parent = if traceparents.next().is_some() {
+        None
+    } else {
+        traceparent.and_then(|value| TraceContext::parse(value).ok())
+    };
+    (request_id, remote_parent)
+}
+
+fn one_auxiliary_header_within_budget(
+    headers: &axum::http::HeaderMap,
+    name: &'static str,
+    validate: fn(&str) -> bool,
+) -> bool {
+    let mut values = headers.get_all(name).iter();
+    let value = values.next().and_then(|value| value.to_str().ok());
+    values.next().is_none() && value.is_some_and(validate)
+}
+
+fn set_canonical_parent(span: &tracing::Span, context: &TraceContext) {
+    let mut headers = axum::http::HeaderMap::new();
+    if let Ok(value) = HeaderValue::from_str(context.traceparent()) {
+        headers.insert("traceparent", value);
+        set_remote_trace_parent(span, &headers);
+    }
+}
@@ -130,7 +130,11 @@ pub struct PostgresTransportSessionStore {

 impl PostgresTransportSessionStore {
    pub async fn from_pool(pool: PgPool) -> Result<Self, SessionStoreError> {
-        apply_postgres_migrations(&pool).await?;
+        crank_registry::MigrationAuthority::require_current(&pool)
+            .await
+            .map_err(|error| SessionStoreError {
+                details: error.to_string(),
+            })?;
        Ok(Self { pool })
    }

@@ -413,124 +417,6 @@ impl TransportSessionStore for PostgresTransportSessionStore {
    }
 }

-async fn apply_postgres_migrations(pool: &PgPool) -> Result<(), SessionStoreError> {
-    let mut transaction = pool.begin().await.map_err(|error| SessionStoreError {
-        details: error.to_string(),
-    })?;
-    query("select pg_advisory_xact_lock($1)")
-        .bind(0x4352_414E_4B4D_4350_i64)
-        .execute(&mut *transaction)
-        .await
-        .map_err(|error| SessionStoreError {
-            details: error.to_string(),
-        })?;
-    query(
-        "create table if not exists __crank_mcp_migrations (
-            version integer primary key,
-            checksum text not null,
-            applied_at timestamptz not null default now()
-        )",
-    )
-    .execute(&mut *transaction)
-    .await
-    .map_err(|error| SessionStoreError {
-        details: error.to_string(),
-    })?;
-    let applied = query("select checksum from __crank_mcp_migrations where version = 1")
-        .fetch_optional(&mut *transaction)
-        .await
-        .map_err(|error| SessionStoreError {
-            details: error.to_string(),
-        })?;
-    if let Some(row) = applied {
-        let checksum = row.get::<String, _>("checksum");
-        if checksum != "mcp-transport-sessions-v1" {
-            return Err(SessionStoreError {
-                details: format!("modified MCP migration version 1: {checksum}"),
-            });
-        }
-        transaction
-            .commit()
-            .await
-            .map_err(|error| SessionStoreError {
-                details: error.to_string(),
-            })?;
-        return Ok(());
-    }
-
-    query(
-        "create table if not exists mcp_transport_sessions (
-            id text primary key,
-            protocol_version text not null,
-            initialized boolean not null default false,
-            supports_elicitation boolean not null default false,
-            workspace_slug text not null,
-            agent_slug text not null,
-            created_at timestamptz not null,
-            updated_at timestamptz not null,
-            expires_at timestamptz null
-        )",
-    )
-    .execute(&mut *transaction)
-    .await
-    .map_err(|error| SessionStoreError {
-        details: error.to_string(),
-    })?;
-
-    query("alter table mcp_transport_sessions add column if not exists supports_elicitation boolean not null default false")
-        .execute(&mut *transaction)
-        .await
-        .map_err(|error| SessionStoreError {
-            details: error.to_string(),
-        })?;
-
-    query(
-        "alter table mcp_transport_sessions add column if not exists expires_at timestamptz null",
-    )
-    .execute(&mut *transaction)
-    .await
-    .map_err(|error| SessionStoreError {
-        details: error.to_string(),
-    })?;
-
-    query(
-        "create index if not exists mcp_transport_sessions_workspace_agent_idx
-         on mcp_transport_sessions(workspace_slug, agent_slug, updated_at desc)",
-    )
-    .execute(&mut *transaction)
-    .await
-    .map_err(|error| SessionStoreError {
-        details: error.to_string(),
-    })?;
-
-    query(
-        "create index if not exists mcp_transport_sessions_expires_at_idx
-         on mcp_transport_sessions(expires_at)
-         where expires_at is not null",
-    )
-    .execute(&mut *transaction)
-    .await
-    .map_err(|error| SessionStoreError {
-        details: error.to_string(),
-    })?;
-
-    query("insert into __crank_mcp_migrations (version, checksum) values (1, $1)")
-        .bind("mcp-transport-sessions-v1")
-        .execute(&mut *transaction)
-        .await
-        .map_err(|error| SessionStoreError {
-            details: error.to_string(),
-        })?;
-    transaction
-        .commit()
-        .await
-        .map_err(|error| SessionStoreError {
-            details: error.to_string(),
-        })?;
-
-    Ok(())
-}
-
 fn is_expired(session: &SessionState, now: OffsetDateTime) -> bool {
    session
        .expires_at
@@ -14,11 +14,13 @@ pub struct ToolErrorContract {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub upstream_status: Option<u16>,
    pub request_id: String,
+    pub trace_id: String,
 }

 pub fn tool_error_contract_from_runtime(
    error: &RuntimeError,
    request_id: &str,
+    trace_id: &str,
 ) -> ToolErrorContract {
    let error_code = runtime_error_code(error);
    ToolErrorContract {
@@ -29,6 +31,7 @@ pub fn tool_error_contract_from_runtime(
        suggested_action: suggested_action(error),
        upstream_status: upstream_status(error),
        request_id: request_id.to_owned(),
+        trace_id: trace_id.to_owned(),
    }
 }

@@ -36,6 +39,7 @@ pub fn generic_tool_error_contract(
    error_code: &'static str,
    message: impl Into<String>,
    request_id: &str,
+    trace_id: &str,
    recoverable: bool,
    suggested_action: Option<&'static str>,
 ) -> ToolErrorContract {
@@ -47,6 +51,7 @@ pub fn generic_tool_error_contract(
        suggested_action,
        upstream_status: None,
        request_id: request_id.to_owned(),
+        trace_id: trace_id.to_owned(),
    }
 }

@@ -64,7 +69,8 @@ pub fn tool_error_value(error: &ToolErrorContract) -> Value {
            "error_code": "runtime_error",
            "message": "Не удалось выполнить инструмент.",
            "recoverable": false,
-            "request_id": error.request_id
+            "request_id": error.request_id,
+            "trace_id": error.trace_id
        })
    })
 }
@@ -109,7 +115,7 @@ fn upstream_status_code(status: u16) -> &'static str {
    }
 }

-fn safe_runtime_error_message(error: &RuntimeError) -> String {
+pub(crate) fn safe_runtime_error_message(error: &RuntimeError) -> String {
    match error {
        RuntimeError::Schema(_) => "Входные параметры не прошли проверку схемы.".to_owned(),
        RuntimeError::Mapping(_) => {
@@ -1,7 +1,7 @@
 use std::{collections::BTreeSet, sync::Arc};

 use axum::{http::StatusCode, response::Response};
-use crank_core::{ToolAccessMode, search_tool_catalog};
+use crank_core::{CorrelationContext, ToolAccessMode, search_tool_catalog};
 use crank_registry::PublishedAgentCatalog;
 use crank_trace::{ErrorCategory, Stage, StageOutcome};
 use serde::Deserialize;
@@ -46,8 +46,9 @@ pub(super) async fn handle_catalog_tool_call(
    catalog: &PublishedAgentCatalog,
    tool_name: &str,
    arguments: Value,
-    transport_request_id: &str,
+    transport_correlation: &CorrelationContext,
 ) -> Response {
+    let transport_request_id = transport_correlation.request_id().as_str();
    match catalog.tool_selection_policy.mode {
        ToolAccessMode::Direct => {
            execute_catalog_tool(
@@ -59,7 +60,7 @@ pub(super) async fn handle_catalog_tool_call(
                catalog,
                tool_name,
                arguments,
-                transport_request_id,
+                transport_correlation,
            )
            .await
        }
@@ -90,6 +91,7 @@ pub(super) async fn handle_catalog_tool_call(
                            proxy.catalog_revision
                        ),
                        transport_request_id,
+                        transport_correlation.trace_id().as_str(),
                        true,
                        Some(
                            "Повторите search_tools и вызовите инструмент с новой версией каталога.",
@@ -106,7 +108,7 @@ pub(super) async fn handle_catalog_tool_call(
                catalog,
                &proxy.name,
                proxy.arguments,
-                transport_request_id,
+                transport_correlation,
            )
            .await
        }
@@ -126,7 +128,7 @@ async fn execute_catalog_tool(
    catalog: &PublishedAgentCatalog,
    tool_name: &str,
    mut arguments: Value,
-    transport_request_id: &str,
+    transport_correlation: &CorrelationContext,
 ) -> Response {
    let resolve_span = Stage::McpToolsResolve.span();
    let resolved = resolve_span.in_scope(|| resolve_generated_tool(&catalog.tools, tool_name));
@@ -158,7 +160,7 @@ async fn execute_catalog_tool(
        resolved,
        arguments,
        confirmation_token,
-        transport_request_id,
+        transport_correlation,
    )
    .await
 }
@@ -1,5 +1,5 @@
 use crank_community_mcp::session::{PostgresTransportSessionStore, TransportSessionStore};
-use crank_registry::PostgresPoolConfig;
+use crank_registry::{MigrationAuthority, PostgresPoolConfig};
 use sqlx::postgres::{PgConnectOptions, PgPoolOptions};
 use time::{OffsetDateTime, format_description::well_known::Rfc3339};

@@ -13,9 +13,15 @@ fn truncate_to_micros(value: OffsetDateTime) -> OffsetDateTime {
        .unwrap()
 }

+async fn migrate(database_url: &str) {
+    let pool = sqlx::PgPool::connect(database_url).await.unwrap();
+    MigrationAuthority::apply(&pool).await.unwrap();
+}
+
 #[tokio::test]
 async fn postgres_transport_sessions_survive_store_reconnect() {
    let database_url = crank_test_support::postgres_schema_url("test_mcp_transport").await;
+    migrate(&database_url).await;
    let connect_options = database_url.parse::<PgConnectOptions>().unwrap();
    let pool_config = PostgresPoolConfig::default();
    let store_a = PostgresTransportSessionStore::connect_with_options_and_pool_config(
@@ -61,6 +67,7 @@ async fn postgres_transport_sessions_survive_store_reconnect() {
 #[tokio::test]
 async fn postgres_transport_sessions_evict_expired_rows_on_read() {
    let database_url = crank_test_support::postgres_schema_url("test_mcp_transport").await;
+    migrate(&database_url).await;
    let connect_options = database_url.parse::<PgConnectOptions>().unwrap();
    let store = PostgresTransportSessionStore::connect_with_options_and_pool_config(
        connect_options.clone(),
@@ -101,6 +108,7 @@ async fn postgres_transport_sessions_evict_expired_rows_on_read() {
 #[tokio::test]
 async fn postgres_transport_session_cleanup_removes_abandoned_expired_rows() {
    let database_url = crank_test_support::postgres_schema_url("test_mcp_cleanup").await;
+    migrate(&database_url).await;
    let store = PostgresTransportSessionStore::connect_with_options_and_pool_config(
        database_url.parse::<PgConnectOptions>().unwrap(),
        PostgresPoolConfig::default(),
@@ -14,12 +14,14 @@ fn maps_upstream_429_to_recoverable_structured_tool_error() {
            }),
        }),
        "req-429",
+        "0af7651916cd43dd8448eb211c80319c",
    );

    assert_eq!(contract.error_code, "upstream_rate_limited");
    assert!(contract.recoverable);
    assert_eq!(contract.upstream_status, Some(429));
    assert_eq!(contract.request_id, "req-429");
+    assert_eq!(contract.trace_id, "0af7651916cd43dd8448eb211c80319c");
    assert_eq!(contract.suggested_action, Some("Повторите запрос позже."));
    assert!(!contract.message.contains("internal_trace"));
 }
@@ -32,12 +34,14 @@ fn maps_mapping_error_to_non_recoverable_structured_tool_error() {
            reason: "expected string".to_owned(),
        },
        "req-map",
+        "0af7651916cd43dd8448eb211c80319c",
    );

    assert_eq!(contract.error_code, "runtime_error");
    assert!(!contract.recoverable);
    assert_eq!(contract.upstream_status, None);
    assert_eq!(contract.request_id, "req-map");
+    assert_eq!(contract.trace_id, "0af7651916cd43dd8448eb211c80319c");
    assert_eq!(
        contract.suggested_action,
        Some("Проверьте параметры вызова инструмента.")
@@ -0,0 +1,13 @@
+[package]
+name = "crank-config"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+rust-version.workspace = true
+publish.workspace = true
+
+[dependencies]
+serde.workspace = true
+serde_json.workspace = true
+sha2.workspace = true
+url.workspace = true
@@ -0,0 +1,73 @@
+use std::{env, fs, path::Path};
+
+use crank_config::render::{
+    BEGIN_MARKER, DOC_BEGIN_MARKER, DOC_END_MARKER, END_MARKER, env_section, reference_section,
+    replace_marked, schema_json,
+};
+
+fn main() {
+    if let Err(error) = run() {
+        eprintln!("config contract check failed: {error}");
+        std::process::exit(1);
+    }
+}
+
+fn run() -> Result<(), String> {
+    let mode = env::args().nth(1).unwrap_or_else(|| "--check".to_owned());
+    if !matches!(mode.as_str(), "--check" | "--write") {
+        return Err("expected --check or --write".to_owned());
+    }
+    let write = mode == "--write";
+    sync_file(
+        Path::new("docs/schemas/runtime-config.schema.json"),
+        schema_json(),
+        write,
+    )?;
+    for (path, production) in [
+        (".env.example", false),
+        ("deploy/community/.env.example", true),
+        ("deploy/community/.env.images.example", true),
+    ] {
+        sync_marked(
+            Path::new(path),
+            BEGIN_MARKER,
+            END_MARKER,
+            &env_section(production),
+            write,
+        )?;
+    }
+    sync_marked(
+        Path::new("docs/runtime-config.md"),
+        DOC_BEGIN_MARKER,
+        DOC_END_MARKER,
+        &reference_section(),
+        write,
+    )?;
+    Ok(())
+}
+
+fn sync_marked(
+    path: &Path,
+    begin: &str,
+    end: &str,
+    replacement: &str,
+    write: bool,
+) -> Result<(), String> {
+    let current =
+        fs::read_to_string(path).map_err(|_| format!("cannot read {}", path.display()))?;
+    let expected = replace_marked(&current, begin, end, replacement)
+        .ok_or_else(|| format!("missing generated markers in {}", path.display()))?;
+    sync_file(path, expected, write)
+}
+
+fn sync_file(path: &Path, expected: String, write: bool) -> Result<(), String> {
+    let current = fs::read_to_string(path).unwrap_or_default();
+    if current == expected {
+        return Ok(());
+    }
+    if write {
+        fs::write(path, expected).map_err(|_| format!("cannot write {}", path.display()))
+    } else {
+        Err(format!("{} is out of date", path.display()))
+    }
+}
@@ -0,0 +1,120 @@
+use std::fmt;
+
+use crate::{
+    AdminProcessConfig, CacheSettings, DatabaseSettings, McpProcessConfig, MetricsSettings,
+    MigratorConfig, ObservabilitySettings, OtlpSettings, OutboundSettings, RuntimeSettings,
+};
+
+impl fmt::Debug for DatabaseSettings {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("DatabaseSettings")
+            .field("url", &self.url.as_ref().map(|_| "configured"))
+            .field("password", &self.password)
+            .field("pool", &self.pool)
+            .finish_non_exhaustive()
+    }
+}
+impl fmt::Debug for CacheSettings {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("CacheSettings")
+            .field("backend", &self.backend)
+            .field("url", &self.url.as_ref().map(|_| "configured"))
+            .finish()
+    }
+}
+impl fmt::Debug for OutboundSettings {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("OutboundSettings")
+            .field("allowed_host_count", &self.allowed_hosts.len())
+            .field("denied_host_count", &self.denied_hosts.len())
+            .field("max_response_bytes", &self.max_response_bytes)
+            .finish()
+    }
+}
+impl fmt::Debug for RuntimeSettings {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("RuntimeSettings")
+            .field("master_key", &self.master_key)
+            .field("base_url", &self.base_url.as_ref().map(|_| "configured"))
+            .field("max_concurrent_unary", &self.max_concurrent_unary)
+            .field("max_concurrent_sessions", &self.max_concurrent_sessions)
+            .field("cache", &self.cache)
+            .field("outbound", &self.outbound)
+            .finish()
+    }
+}
+impl fmt::Debug for MetricsSettings {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("MetricsSettings")
+            .field("enabled", &self.enabled)
+            .field("loopback", &self.bind_addr.ip().is_loopback())
+            .field(
+                "bearer_token",
+                &self.bearer_token.as_ref().map(|_| "configured"),
+            )
+            .finish()
+    }
+}
+impl fmt::Debug for OtlpSettings {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("OtlpSettings")
+            .field("endpoint", &self.endpoint.as_ref().map(|_| "configured"))
+            .field(
+                "traces_endpoint",
+                &self.traces_endpoint.as_ref().map(|_| "configured"),
+            )
+            .field("headers", &self.headers.as_ref().map(|_| "configured"))
+            .field(
+                "traces_headers",
+                &self.traces_headers.as_ref().map(|_| "configured"),
+            )
+            .field("max_queue_size", &self.max_queue_size)
+            .field("max_export_batch_size", &self.max_export_batch_size)
+            .finish_non_exhaustive()
+    }
+}
+impl fmt::Debug for ObservabilitySettings {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("ObservabilitySettings")
+            .field("environment", &"configured")
+            .field("log_filter", &"configured")
+            .field(
+                "sentry_dsn",
+                &self.sentry_dsn.as_ref().map(|_| "configured"),
+            )
+            .field("metrics", &self.metrics)
+            .field("otlp", &self.otlp)
+            .finish()
+    }
+}
+impl fmt::Debug for AdminProcessConfig {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("AdminProcessConfig")
+            .field("database", &self.database)
+            .field("runtime", &self.runtime)
+            .field("observability", &self.observability)
+            .field("storage_root", &"configured")
+            .field("session_secret", &self.session_secret)
+            .field("password_pepper", &self.password_pepper)
+            .field("bootstrap_password", &self.bootstrap_password)
+            .finish_non_exhaustive()
+    }
+}
+impl fmt::Debug for McpProcessConfig {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("McpProcessConfig")
+            .field("database", &self.database)
+            .field("runtime", &self.runtime)
+            .field("observability", &self.observability)
+            .finish_non_exhaustive()
+    }
+}
+
+impl fmt::Debug for MigratorConfig {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("MigratorConfig")
+            .field("database", &self.database)
+            .field("fingerprint", &self.fingerprint())
+            .finish()
+    }
+}
@@ -0,0 +1,206 @@
+use std::fmt;
+
+use serde::{Serialize, Serializer};
+
+const MAX_DIAGNOSTICS: usize = 100;
+
+#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
+pub enum DiagnosticCode {
+    MissingRequired,
+    InvalidEncoding,
+    InvalidType,
+    OutOfRange,
+    UnknownField,
+    Conflict,
+    UnsafeCombination,
+    DeprecatedNoEffect,
+}
+
+impl Serialize for DiagnosticCode {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+    {
+        serializer.serialize_str(self.as_str())
+    }
+}
+
+impl DiagnosticCode {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::MissingRequired => "config.missing_required",
+            Self::InvalidEncoding => "config.invalid_encoding",
+            Self::InvalidType => "config.invalid_type",
+            Self::OutOfRange => "config.out_of_range",
+            Self::UnknownField => "config.unknown_field",
+            Self::Conflict => "config.conflict",
+            Self::UnsafeCombination => "config.unsafe_combination",
+            Self::DeprecatedNoEffect => "config.deprecated_no_effect",
+        }
+    }
+}
+
+#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd, Serialize)]
+pub struct Diagnostic {
+    pub code: DiagnosticCode,
+    pub field: String,
+    pub message_ru: &'static str,
+    pub message_en: &'static str,
+}
+
+impl Diagnostic {
+    pub(crate) fn new(code: DiagnosticCode, field: impl Into<String>) -> Self {
+        let (message_ru, message_en) = match code {
+            DiagnosticCode::MissingRequired => (
+                "Обязательный параметр не настроен.",
+                "A required configuration field is not configured.",
+            ),
+            DiagnosticCode::InvalidEncoding => (
+                "Параметр должен быть корректной строкой UTF-8.",
+                "The configuration field must be valid UTF-8.",
+            ),
+            DiagnosticCode::InvalidType => (
+                "Параметр имеет недопустимый тип или формат.",
+                "The configuration field has an invalid type or format.",
+            ),
+            DiagnosticCode::OutOfRange => (
+                "Параметр находится вне допустимых границ.",
+                "The configuration field is outside its allowed bounds.",
+            ),
+            DiagnosticCode::UnknownField => (
+                "Неизвестный параметр в управляемом пространстве имён.",
+                "Unknown field in an owned configuration namespace.",
+            ),
+            DiagnosticCode::Conflict => (
+                "Одновременно заданы конфликтующие источники конфигурации.",
+                "Conflicting configuration sources are set at the same time.",
+            ),
+            DiagnosticCode::UnsafeCombination => (
+                "Комбинация параметров небезопасна или противоречива.",
+                "The configuration combination is unsafe or inconsistent.",
+            ),
+            DiagnosticCode::DeprecatedNoEffect => (
+                "Устаревший параметр не имеет поддерживаемого эффекта.",
+                "The deprecated field has no supported effect.",
+            ),
+        };
+        let mut field = field.into();
+        if field.len() > 256 {
+            let mut boundary = 256;
+            while !field.is_char_boundary(boundary) {
+                boundary -= 1;
+            }
+            field.truncate(boundary);
+        }
+        Self {
+            code,
+            field,
+            message_ru,
+            message_en,
+        }
+    }
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ConfigError {
+    diagnostics: Vec<Diagnostic>,
+    omitted: usize,
+}
+
+impl ConfigError {
+    pub fn single(code: DiagnosticCode, field: impl Into<String>) -> Self {
+        Self::from_diagnostics(vec![Diagnostic::new(code, field)])
+    }
+
+    pub(crate) fn from_diagnostics(mut diagnostics: Vec<Diagnostic>) -> Self {
+        diagnostics.sort();
+        diagnostics.dedup();
+        let mut omitted = diagnostics.len().saturating_sub(MAX_DIAGNOSTICS);
+        diagnostics.truncate(MAX_DIAGNOSTICS);
+        while serialized_len(&diagnostics, omitted) > 65_536 && !diagnostics.is_empty() {
+            diagnostics.pop();
+            omitted += 1;
+        }
+        Self {
+            diagnostics,
+            omitted,
+        }
+    }
+
+    pub fn diagnostics(&self) -> &[Diagnostic] {
+        &self.diagnostics
+    }
+
+    pub fn omitted(&self) -> usize {
+        self.omitted
+    }
+
+    pub fn to_json(&self) -> String {
+        #[derive(Serialize)]
+        struct Report<'a> {
+            diagnostics: &'a [Diagnostic],
+            omitted: usize,
+        }
+        serde_json::to_string(&Report {
+            diagnostics: &self.diagnostics,
+            omitted: self.omitted,
+        })
+        .unwrap_or_else(|_| "{\"diagnostics\":[],\"omitted\":0}".to_owned())
+    }
+}
+
+fn serialized_len(diagnostics: &[Diagnostic], omitted: usize) -> usize {
+    #[derive(Serialize)]
+    struct Report<'a> {
+        diagnostics: &'a [Diagnostic],
+        omitted: usize,
+    }
+    serde_json::to_vec(&Report {
+        diagnostics,
+        omitted,
+    })
+    .map_or(usize::MAX, |value| value.len())
+}
+
+impl fmt::Display for ConfigError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        for (index, diagnostic) in self.diagnostics.iter().enumerate() {
+            if index > 0 {
+                formatter.write_str("; ")?;
+            }
+            write!(
+                formatter,
+                "{} field={} ru={} en={}",
+                diagnostic.code.as_str(),
+                diagnostic.field,
+                diagnostic.message_ru,
+                diagnostic.message_en
+            )?;
+        }
+        if self.omitted > 0 {
+            write!(formatter, "; diagnostics_omitted={}", self.omitted)?;
+        }
+        Ok(())
+    }
+}
+
+impl std::error::Error for ConfigError {}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn unicode_fields_and_worst_case_json_remain_bounded() {
+        let field = format!("{}{}", "\\\"".repeat(120), "💣".repeat(100));
+        let diagnostics = (0..200)
+            .map(|index| Diagnostic::new(DiagnosticCode::InvalidType, format!("{index}:{field}")))
+            .collect();
+        let error = ConfigError::from_diagnostics(diagnostics);
+        let json = error.to_json();
+        assert!(json.len() <= 65_536);
+        assert!(error.omitted() > 0);
+        assert!(serde_json::from_str::<serde_json::Value>(&json).is_ok());
+        assert!(json.contains("config.invalid_type"));
+    }
+}
@@ -0,0 +1,11 @@
+use sha2::{Digest, Sha256};
+
+pub(crate) fn sha256_hex(parts: impl IntoIterator<Item = String>) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(b"crank-config-fingerprint-v1\0");
+    for part in parts {
+        hasher.update(part.len().to_le_bytes());
+        hasher.update(part.as_bytes());
+    }
+    format!("{:x}", hasher.finalize())
+}
@@ -0,0 +1,25 @@
+//! Typed bootstrap configuration contract for Crank processes.
+
+mod debug;
+mod diagnostic;
+mod fingerprint;
+mod migrator;
+mod process;
+pub mod render;
+mod schema;
+mod source;
+mod validation;
+mod value;
+
+pub use diagnostic::{ConfigError, Diagnostic, DiagnosticCode};
+pub use migrator::{MigratorConfig, parse_migrator};
+pub use process::{
+    AdminProcessConfig, CacheBackend, CacheSettings, DatabaseSettings, DeprecationRecord,
+    EffectiveConfig, McpProcessConfig, MetricsSettings, ObservabilitySettings, OtlpSettings,
+    OutboundSettings, PoolSettings, ProcessKind, RateLimitSettings, RuntimeSettings, parse_process,
+};
+pub use schema::{
+    FieldMode, FieldSpec, ProcessScope, Sensitivity, deployment_field_registry, field_registry,
+};
+pub use source::ConfigSource;
+pub use value::SecretString;
@@ -0,0 +1,47 @@
+use crate::{
+    ConfigError, ConfigSource, DatabaseSettings, DeprecationRecord, fingerprint::sha256_hex,
+    process::parse_database_source,
+};
+
+#[derive(Clone)]
+pub struct MigratorConfig {
+    pub database: DatabaseSettings,
+    fingerprint: String,
+    deprecations: Vec<DeprecationRecord>,
+}
+
+impl MigratorConfig {
+    pub fn fingerprint(&self) -> &str {
+        &self.fingerprint
+    }
+
+    pub fn deprecations(&self) -> &[DeprecationRecord] {
+        &self.deprecations
+    }
+}
+
+pub fn parse_migrator(source: ConfigSource) -> Result<MigratorConfig, ConfigError> {
+    let (database, deprecations) = parse_database_source(source.retain_for_migrator())?;
+    let fingerprint = sha256_hex([
+        "schema=crank-config-migrator-v1".to_owned(),
+        format!("url={}", database.url.is_some()),
+        format!("host={}", database.host.to_ascii_lowercase()),
+        format!("port={}", database.port),
+        format!("database={}", database.database),
+        format!("username={}", database.username),
+        format!("password={}", database.password.is_configured()),
+        format!(
+            "pool={}:{}:{}:{}:{}",
+            database.pool.max_connections,
+            database.pool.min_connections,
+            database.pool.acquire_timeout_ms,
+            database.pool.idle_timeout_ms,
+            database.pool.max_lifetime_ms
+        ),
+    ]);
+    Ok(MigratorConfig {
+        database,
+        fingerprint,
+        deprecations,
+    })
+}
@@ -0,0 +1,110 @@
+use serde::Serialize;
+
+use crate::{FieldMode, FieldSpec, Sensitivity, deployment_field_registry, field_registry};
+
+pub const BEGIN_MARKER: &str = "# BEGIN GENERATED CRANK RUNTIME CONFIG";
+pub const END_MARKER: &str = "# END GENERATED CRANK RUNTIME CONFIG";
+pub const DOC_BEGIN_MARKER: &str = "<!-- BEGIN GENERATED CRANK RUNTIME CONFIG -->";
+pub const DOC_END_MARKER: &str = "<!-- END GENERATED CRANK RUNTIME CONFIG -->";
+
+#[derive(Serialize)]
+struct RuntimeContract<'a> {
+    schema_version: u32,
+    generated_by: &'static str,
+    fields: &'a [FieldSpec],
+    deployment_only_fields: &'static [&'static str],
+}
+
+pub fn schema_json() -> String {
+    let contract = RuntimeContract {
+        schema_version: 1,
+        generated_by: "crank-config",
+        fields: field_registry(),
+        deployment_only_fields: deployment_field_registry(),
+    };
+    let mut rendered = serde_json::to_string_pretty(&contract).expect("static contract serializes");
+    rendered.push('\n');
+    rendered
+}
+
+pub fn env_section(production: bool) -> String {
+    let mut output = String::new();
+    output.push_str(BEGIN_MARKER);
+    output.push('\n');
+    for field in field_registry()
+        .iter()
+        .filter(|field| field.mode == FieldMode::Effective)
+    {
+        let value = example_value(field, production);
+        output.push_str(field.env_name);
+        output.push('=');
+        output.push_str(&value);
+        output.push('\n');
+    }
+    output.push_str(END_MARKER);
+    output.push('\n');
+    output
+}
+
+pub fn reference_section() -> String {
+    let mut output = String::new();
+    output.push_str(DOC_BEGIN_MARKER);
+    output.push_str("\n\n| Environment | Semantic path | Process | Type/unit | Default | Bounds | Sensitivity | Mode |\n");
+    output.push_str("|---|---|---|---|---|---|---|---|\n");
+    for field in field_registry() {
+        let unit = field.unit.unwrap_or("-");
+        let default = match (field.sensitivity, field.default, field.required) {
+            (Sensitivity::Secret, Some(_), _) => "configured",
+            (Sensitivity::Secret, None, true) => "required/blank",
+            (Sensitivity::Secret, None, false) => "blank",
+            (_, Some(default), _) => default,
+            (_, None, true) => "required/blank",
+            (_, None, false) => "blank",
+        };
+        let bounds = match (field.minimum, field.maximum) {
+            (Some(minimum), Some(maximum)) => format!("{minimum}..={maximum}"),
+            _ => "-".to_owned(),
+        };
+        output.push_str(&format!(
+            "| `{}` | `{}` | `{:?}` | `{}/{}` | `{}` | `{}` | `{:?}` | `{:?}` |\n",
+            field.env_name,
+            field.semantic_path,
+            field.process,
+            field.value_type,
+            unit,
+            default,
+            bounds,
+            field.sensitivity,
+            field.mode,
+        ));
+    }
+    output.push('\n');
+    output.push_str(DOC_END_MARKER);
+    output.push('\n');
+    output
+}
+
+pub fn replace_marked(content: &str, begin: &str, end: &str, replacement: &str) -> Option<String> {
+    let start = content.find(begin)?;
+    let tail = &content[start..];
+    let end_offset = tail.find(end)? + end.len();
+    let suffix_start = start + end_offset;
+    let mut rendered = String::with_capacity(content.len() + replacement.len());
+    rendered.push_str(&content[..start]);
+    rendered.push_str(replacement.trim_end());
+    rendered.push_str(&content[suffix_start..]);
+    Some(rendered)
+}
+
+fn example_value(field: &FieldSpec, production: bool) -> String {
+    if field.sensitivity == Sensitivity::Secret {
+        return String::new();
+    }
+    match (field.env_name, production) {
+        ("CRANK_ENVIRONMENT", true) => "production".to_owned(),
+        ("CRANK_BASE_URL", _) => "http://localhost:3000".to_owned(),
+        ("POSTGRES_HOST", true) => "postgres".to_owned(),
+        ("CRANK_TRUST_FORWARDED_HEADERS", true) => "true".to_owned(),
+        _ => field.default.unwrap_or("").to_owned(),
+    }
+}
@@ -0,0 +1,797 @@
+use serde::Serialize;
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ProcessScope {
+    Shared,
+    AdminApi,
+    McpServer,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Sensitivity {
+    Public,
+    Internal,
+    Secret,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum FieldMode {
+    Effective,
+    DeprecatedNoEffect,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
+pub struct FieldSpec {
+    pub semantic_path: &'static str,
+    pub env_name: &'static str,
+    pub process: ProcessScope,
+    pub value_type: &'static str,
+    pub unit: Option<&'static str>,
+    pub default: Option<&'static str>,
+    pub required: bool,
+    pub minimum: Option<u64>,
+    pub maximum: Option<u64>,
+    pub sensitivity: Sensitivity,
+    pub mode: FieldMode,
+    pub compatibility: Option<&'static str>,
+    pub rules: &'static [&'static str],
+}
+
+impl FieldSpec {
+    pub fn default_for(self, process: ProcessScope) -> Option<&'static str> {
+        match (self.env_name, process) {
+            ("CRANK_BASE_URL", ProcessScope::AdminApi) => Some("http://localhost:3000"),
+            ("CRANK_LOG_LEVEL", ProcessScope::AdminApi) => Some("admin_api=info,tower_http=info"),
+            ("CRANK_LOG_LEVEL", ProcessScope::McpServer) => Some("mcp_server=info,tower_http=info"),
+            _ => self.default,
+        }
+    }
+}
+
+pub(crate) fn semantic_path_for(env_name: &str) -> &str {
+    field_registry()
+        .iter()
+        .find(|field| field.env_name == env_name)
+        .map_or(env_name, |field| field.semantic_path)
+}
+
+macro_rules! f {
+    ($path:literal,$name:literal,$proc:ident,$type:literal,$unit:expr,$default:expr,$min:expr,$max:expr,$sensitivity:ident) => {
+        FieldSpec {
+            semantic_path: $path,
+            env_name: $name,
+            process: ProcessScope::$proc,
+            value_type: $type,
+            unit: $unit,
+            default: $default,
+            required: false,
+            minimum: $min,
+            maximum: $max,
+            sensitivity: Sensitivity::$sensitivity,
+            mode: FieldMode::Effective,
+            compatibility: None,
+            rules: &[],
+        }
+    };
+}
+
+static FIELDS: [FieldSpec; 57] = [
+    FieldSpec {
+        compatibility: Some("legacy URL form"),
+        rules: &[
+            "takes precedence over generated default-valued POSTGRES_HOST/PORT/DB/USER/PASSWORD",
+            "conflicts with any non-default decomposed database value",
+        ],
+        ..f!(
+            "database.url",
+            "CRANK_DATABASE_URL",
+            Shared,
+            "url",
+            None,
+            None,
+            None,
+            None,
+            Secret
+        )
+    },
+    f!(
+        "database.host",
+        "POSTGRES_HOST",
+        Shared,
+        "string",
+        None,
+        Some("postgres"),
+        None,
+        None,
+        Internal
+    ),
+    f!(
+        "database.port",
+        "POSTGRES_PORT",
+        Shared,
+        "u16",
+        Some("port"),
+        Some("5432"),
+        Some(1),
+        Some(65535),
+        Public
+    ),
+    f!(
+        "database.name",
+        "POSTGRES_DB",
+        Shared,
+        "string",
+        None,
+        Some("crank"),
+        None,
+        None,
+        Internal
+    ),
+    f!(
+        "database.user",
+        "POSTGRES_USER",
+        Shared,
+        "string",
+        None,
+        Some("crank"),
+        None,
+        None,
+        Internal
+    ),
+    f!(
+        "database.password",
+        "POSTGRES_PASSWORD",
+        Shared,
+        "secret",
+        None,
+        Some("configured"),
+        None,
+        None,
+        Secret
+    ),
+    FieldSpec {
+        rules: &["must be >= min_connections"],
+        ..f!(
+            "database.pool.max_connections",
+            "POSTGRES_MAX_CONNECTIONS",
+            Shared,
+            "u32",
+            Some("connections"),
+            Some("20"),
+            Some(1),
+            Some(1024),
+            Public
+        )
+    },
+    FieldSpec {
+        rules: &["must be <= max_connections"],
+        ..f!(
+            "database.pool.min_connections",
+            "POSTGRES_MIN_CONNECTIONS",
+            Shared,
+            "u32",
+            Some("connections"),
+            Some("2"),
+            Some(0),
+            Some(1024),
+            Public
+        )
+    },
+    f!(
+        "database.pool.acquire_timeout_ms",
+        "POSTGRES_ACQUIRE_TIMEOUT_MS",
+        Shared,
+        "u64",
+        Some("milliseconds"),
+        Some("5000"),
+        Some(1),
+        Some(300000),
+        Public
+    ),
+    f!(
+        "database.pool.idle_timeout_ms",
+        "POSTGRES_IDLE_TIMEOUT_MS",
+        Shared,
+        "u64",
+        Some("milliseconds"),
+        Some("600000"),
+        Some(1000),
+        Some(86400000),
+        Public
+    ),
+    f!(
+        "database.pool.max_lifetime_ms",
+        "POSTGRES_MAX_LIFETIME_MS",
+        Shared,
+        "u64",
+        Some("milliseconds"),
+        Some("1800000"),
+        Some(1000),
+        Some(86400000),
+        Public
+    ),
+    FieldSpec {
+        required: true,
+        ..f!(
+            "runtime.master_key",
+            "CRANK_MASTER_KEY",
+            Shared,
+            "secret",
+            None,
+            None,
+            None,
+            None,
+            Secret
+        )
+    },
+    f!(
+        "runtime.base_url",
+        "CRANK_BASE_URL",
+        Shared,
+        "url",
+        None,
+        None,
+        None,
+        None,
+        Internal
+    ),
+    f!(
+        "runtime.max_concurrent_unary",
+        "CRANK_RUNTIME_MAX_CONCURRENT_UNARY",
+        Shared,
+        "u32",
+        Some("requests"),
+        Some("64"),
+        Some(1),
+        Some(65535),
+        Public
+    ),
+    FieldSpec {
+        compatibility: Some("redis value is deprecated in favor of valkey"),
+        rules: &["external backend requires cache.url"],
+        ..f!(
+            "cache.backend",
+            "CRANK_CACHE_BACKEND",
+            Shared,
+            "enum",
+            None,
+            Some("memory"),
+            None,
+            None,
+            Public
+        )
+    },
+    FieldSpec {
+        rules: &["forbidden with memory backend"],
+        ..f!(
+            "cache.url",
+            "CRANK_CACHE_URL",
+            Shared,
+            "url",
+            None,
+            None,
+            None,
+            None,
+            Secret
+        )
+    },
+    FieldSpec {
+        mode: FieldMode::DeprecatedNoEffect,
+        ..f!(
+            "cache.default_ttl_ms",
+            "CRANK_CACHE_DEFAULT_TTL_MS",
+            Shared,
+            "u64",
+            Some("milliseconds"),
+            None,
+            Some(1),
+            Some(86400000),
+            Public
+        )
+    },
+    f!(
+        "outbound.allowed_hosts",
+        "CRANK_OUTBOUND_ALLOWED_HOSTS",
+        Shared,
+        "host_list",
+        None,
+        Some(""),
+        None,
+        None,
+        Internal
+    ),
+    FieldSpec {
+        rules: &["deny entries override allow entries"],
+        ..f!(
+            "outbound.denied_hosts",
+            "CRANK_OUTBOUND_DENIED_HOSTS",
+            Shared,
+            "host_list",
+            None,
+            Some(""),
+            None,
+            None,
+            Internal
+        )
+    },
+    f!(
+        "outbound.max_response_bytes",
+        "CRANK_OUTBOUND_MAX_RESPONSE_BYTES",
+        Shared,
+        "u64",
+        Some("bytes"),
+        Some("4194304"),
+        Some(1),
+        Some(67108864),
+        Public
+    ),
+    f!(
+        "observability.environment",
+        "CRANK_ENVIRONMENT",
+        Shared,
+        "label",
+        None,
+        Some("development"),
+        None,
+        None,
+        Public
+    ),
+    f!(
+        "observability.log_filter",
+        "CRANK_LOG_LEVEL",
+        Shared,
+        "string",
+        None,
+        None,
+        None,
+        None,
+        Public
+    ),
+    f!(
+        "observability.sentry_dsn",
+        "CRANK_SENTRY_DSN",
+        Shared,
+        "url",
+        None,
+        None,
+        None,
+        None,
+        Secret
+    ),
+    FieldSpec {
+        compatibility: Some("yes/no/on/off spellings are deprecated"),
+        ..f!(
+            "observability.metrics.enabled",
+            "CRANK_METRICS_ENABLED",
+            Shared,
+            "bool",
+            None,
+            Some("true"),
+            None,
+            None,
+            Public
+        )
+    },
+    FieldSpec {
+        rules: &["required when an enabled metrics bind is non-loopback"],
+        ..f!(
+            "observability.metrics.bearer_token",
+            "CRANK_METRICS_BEARER_TOKEN",
+            Shared,
+            "secret",
+            None,
+            None,
+            None,
+            None,
+            Secret
+        )
+    },
+    f!(
+        "observability.otlp.endpoint",
+        "OTEL_EXPORTER_OTLP_ENDPOINT",
+        Shared,
+        "url",
+        None,
+        None,
+        None,
+        None,
+        Internal
+    ),
+    FieldSpec {
+        rules: &["overrides generic OTLP endpoint"],
+        ..f!(
+            "observability.otlp.traces_endpoint",
+            "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
+            Shared,
+            "url",
+            None,
+            None,
+            None,
+            None,
+            Internal
+        )
+    },
+    f!(
+        "observability.otlp.protocol",
+        "OTEL_EXPORTER_OTLP_PROTOCOL",
+        Shared,
+        "enum",
+        None,
+        Some("http/protobuf"),
+        None,
+        None,
+        Public
+    ),
+    f!(
+        "observability.otlp.traces_protocol",
+        "OTEL_EXPORTER_OTLP_TRACES_PROTOCOL",
+        Shared,
+        "enum",
+        None,
+        None,
+        None,
+        None,
+        Public
+    ),
+    f!(
+        "observability.otlp.timeout",
+        "OTEL_EXPORTER_OTLP_TIMEOUT",
+        Shared,
+        "duration",
+        Some("milliseconds"),
+        Some("10000"),
+        Some(1),
+        Some(300000),
+        Public
+    ),
+    f!(
+        "observability.otlp.traces_timeout",
+        "OTEL_EXPORTER_OTLP_TRACES_TIMEOUT",
+        Shared,
+        "duration",
+        Some("milliseconds"),
+        None,
+        Some(1),
+        Some(300000),
+        Public
+    ),
+    f!(
+        "observability.otlp.headers",
+        "OTEL_EXPORTER_OTLP_HEADERS",
+        Shared,
+        "headers",
+        None,
+        None,
+        None,
+        None,
+        Secret
+    ),
+    f!(
+        "observability.otlp.traces_headers",
+        "OTEL_EXPORTER_OTLP_TRACES_HEADERS",
+        Shared,
+        "headers",
+        None,
+        None,
+        None,
+        None,
+        Secret
+    ),
+    f!(
+        "observability.otlp.max_queue_size",
+        "OTEL_BSP_MAX_QUEUE_SIZE",
+        Shared,
+        "u32",
+        Some("spans"),
+        Some("2048"),
+        Some(1),
+        Some(65536),
+        Public
+    ),
+    FieldSpec {
+        rules: &["must be <= max_queue_size"],
+        ..f!(
+            "observability.otlp.max_export_batch_size",
+            "OTEL_BSP_MAX_EXPORT_BATCH_SIZE",
+            Shared,
+            "u32",
+            Some("spans"),
+            Some("512"),
+            Some(1),
+            Some(65536),
+            Public
+        )
+    },
+    f!(
+        "observability.otlp.schedule_delay",
+        "OTEL_BSP_SCHEDULE_DELAY",
+        Shared,
+        "duration",
+        Some("milliseconds"),
+        Some("5000"),
+        Some(1),
+        Some(300000),
+        Public
+    ),
+    f!(
+        "observability.otlp.export_timeout",
+        "OTEL_BSP_EXPORT_TIMEOUT",
+        Shared,
+        "duration",
+        Some("milliseconds"),
+        Some("30000"),
+        Some(1),
+        Some(300000),
+        Public
+    ),
+    f!(
+        "admin.bind",
+        "CRANK_ADMIN_BIND",
+        AdminApi,
+        "socket",
+        None,
+        Some("0.0.0.0:3001"),
+        None,
+        None,
+        Internal
+    ),
+    f!(
+        "admin.metrics_bind",
+        "CRANK_ADMIN_METRICS_BIND",
+        AdminApi,
+        "socket",
+        None,
+        Some("127.0.0.1:9464"),
+        None,
+        None,
+        Internal
+    ),
+    f!(
+        "admin.storage_root",
+        "CRANK_STORAGE_ROOT",
+        AdminApi,
+        "absolute_path",
+        None,
+        Some("/var/lib/crank/storage"),
+        None,
+        None,
+        Internal
+    ),
+    f!(
+        "admin.rate_limit.rps",
+        "CRANK_ADMIN_RATE_LIMIT_RPS",
+        AdminApi,
+        "u32",
+        Some("requests_per_second"),
+        Some("30"),
+        Some(1),
+        Some(100000),
+        Public
+    ),
+    FieldSpec {
+        rules: &["must be >= admin rate RPS"],
+        ..f!(
+            "admin.rate_limit.burst",
+            "CRANK_ADMIN_RATE_LIMIT_BURST",
+            AdminApi,
+            "u32",
+            Some("requests"),
+            Some("60"),
+            Some(1),
+            Some(1000000),
+            Public
+        )
+    },
+    f!(
+        "admin.invocation_log_retention_days",
+        "CRANK_INVOCATION_LOG_RETENTION_DAYS",
+        AdminApi,
+        "u32",
+        Some("days"),
+        Some("30"),
+        Some(1),
+        Some(36500),
+        Public
+    ),
+    FieldSpec {
+        required: true,
+        ..f!(
+            "admin.session.secret",
+            "CRANK_SESSION_SECRET",
+            AdminApi,
+            "secret",
+            None,
+            None,
+            None,
+            None,
+            Secret
+        )
+    },
+    FieldSpec {
+        required: true,
+        ..f!(
+            "admin.password_pepper",
+            "CRANK_PASSWORD_PEPPER",
+            AdminApi,
+            "secret",
+            None,
+            None,
+            None,
+            None,
+            Secret
+        )
+    },
+    f!(
+        "admin.session.ttl_hours",
+        "CRANK_SESSION_TTL_HOURS",
+        AdminApi,
+        "u32",
+        Some("hours"),
+        Some("24"),
+        Some(1),
+        Some(8760),
+        Public
+    ),
+    FieldSpec {
+        compatibility: Some("yes/no/on/off spellings are deprecated"),
+        ..f!(
+            "admin.trust_forwarded_headers",
+            "CRANK_TRUST_FORWARDED_HEADERS",
+            AdminApi,
+            "bool",
+            None,
+            Some("false"),
+            None,
+            None,
+            Public
+        )
+    },
+    FieldSpec {
+        required: true,
+        ..f!(
+            "admin.bootstrap.email",
+            "CRANK_BOOTSTRAP_ADMIN_EMAIL",
+            AdminApi,
+            "string",
+            None,
+            None,
+            None,
+            None,
+            Internal
+        )
+    },
+    FieldSpec {
+        required: true,
+        ..f!(
+            "admin.bootstrap.password",
+            "CRANK_BOOTSTRAP_ADMIN_PASSWORD",
+            AdminApi,
+            "secret",
+            None,
+            None,
+            None,
+            None,
+            Secret
+        )
+    },
+    f!(
+        "admin.bootstrap.display_name",
+        "CRANK_BOOTSTRAP_ADMIN_DISPLAY_NAME",
+        AdminApi,
+        "string",
+        None,
+        Some("Crank Owner"),
+        None,
+        None,
+        Internal
+    ),
+    FieldSpec {
+        compatibility: Some("yes/no/on/off spellings are deprecated"),
+        ..f!(
+            "admin.demo_seed",
+            "CRANK_DEMO_SEED",
+            AdminApi,
+            "bool",
+            None,
+            Some("false"),
+            None,
+            None,
+            Public
+        )
+    },
+    f!(
+        "mcp.bind",
+        "CRANK_MCP_BIND",
+        McpServer,
+        "socket",
+        None,
+        Some("0.0.0.0:3002"),
+        None,
+        None,
+        Internal
+    ),
+    f!(
+        "mcp.metrics_bind",
+        "CRANK_MCP_METRICS_BIND",
+        McpServer,
+        "socket",
+        None,
+        Some("127.0.0.1:9465"),
+        None,
+        None,
+        Internal
+    ),
+    f!(
+        "mcp.refresh_ms",
+        "CRANK_MCP_REFRESH_MS",
+        McpServer,
+        "u64",
+        Some("milliseconds"),
+        Some("5000"),
+        Some(100),
+        Some(3600000),
+        Public
+    ),
+    f!(
+        "mcp.rate_limit.rps",
+        "CRANK_MCP_RATE_LIMIT_RPS",
+        McpServer,
+        "u32",
+        Some("requests_per_second"),
+        Some("60"),
+        Some(1),
+        Some(100000),
+        Public
+    ),
+    FieldSpec {
+        rules: &["must be >= MCP rate RPS"],
+        ..f!(
+            "mcp.rate_limit.burst",
+            "CRANK_MCP_RATE_LIMIT_BURST",
+            McpServer,
+            "u32",
+            Some("requests"),
+            Some("120"),
+            Some(1),
+            Some(1000000),
+            Public
+        )
+    },
+    f!(
+        "runtime.max_concurrent_sessions",
+        "CRANK_RUNTIME_MAX_CONCURRENT_SESSIONS",
+        McpServer,
+        "u32",
+        Some("sessions"),
+        Some("16"),
+        Some(1),
+        Some(65535),
+        Public
+    ),
+];
+
+pub fn field_registry() -> &'static [FieldSpec] {
+    &FIELDS
+}
+
+static DEPLOYMENT_FIELDS: [&str; 12] = [
+    "COMPOSE_PROJECT_NAME",
+    "POSTGRES_PUBLISH_BIND",
+    "POSTGRES_PUBLISH_PORT",
+    "CRANK_ADMIN_API_IMAGE",
+    "CRANK_MCP_SERVER_IMAGE",
+    "CRANK_UI_IMAGE",
+    "CRANK_PUBLISH_BIND",
+    "CRANK_ADMIN_PUBLISH_PORT",
+    "CRANK_MCP_PUBLISH_PORT",
+    "CRANK_UI_PUBLISH_PORT",
+    "VALKEY_PUBLISH_BIND",
+    "VALKEY_PUBLISH_PORT",
+];
+
+pub fn deployment_field_registry() -> &'static [&'static str] {
+    &DEPLOYMENT_FIELDS
+}
@@ -0,0 +1,85 @@
+use std::{collections::BTreeMap, ffi::OsString};
+
+use crate::{ConfigError, Diagnostic, DiagnosticCode, deployment_field_registry, field_registry};
+
+#[derive(Clone, Debug, Default)]
+pub struct ConfigSource {
+    values: BTreeMap<String, String>,
+}
+
+impl ConfigSource {
+    pub fn from_utf8(values: BTreeMap<String, String>) -> Self {
+        Self { values }
+    }
+
+    pub fn from_os() -> Result<Self, ConfigError> {
+        Self::from_os_iter(std::env::vars_os())
+    }
+
+    pub fn from_os_for_migrator() -> Result<Self, ConfigError> {
+        Self::from_os_iter_filtered(std::env::vars_os(), |name| {
+            name.starts_with("POSTGRES_") || name.starts_with("CRANK_DATABASE_")
+        })
+    }
+
+    pub fn from_os_iter<I>(values: I) -> Result<Self, ConfigError>
+    where
+        I: IntoIterator<Item = (OsString, OsString)>,
+    {
+        Self::from_os_iter_filtered(values, |_| true)
+    }
+
+    fn from_os_iter_filtered<I, F>(values: I, include: F) -> Result<Self, ConfigError>
+    where
+        I: IntoIterator<Item = (OsString, OsString)>,
+        F: Fn(&str) -> bool,
+    {
+        let mut parsed = BTreeMap::new();
+        let mut diagnostics = Vec::new();
+        for (name, value) in values {
+            let Ok(name) = name.into_string() else {
+                // Owned names are ASCII. A non-UTF-8 name therefore cannot belong
+                // to Crank and must not make startup depend on unrelated OS state.
+                continue;
+            };
+            if !include(&name) {
+                continue;
+            }
+            let owned = name.starts_with("CRANK_")
+                || name.starts_with("POSTGRES_")
+                || name.starts_with("OTEL_");
+            let known = field_registry().iter().any(|field| field.env_name == name)
+                || deployment_field_registry().contains(&name.as_str());
+            if !owned && !known {
+                continue;
+            }
+            let value = match value.into_string() {
+                Ok(value) => value,
+                Err(_) => {
+                    let field = field_registry()
+                        .iter()
+                        .find(|field| field.env_name == name)
+                        .map_or("environment.unknown", |field| field.semantic_path);
+                    diagnostics.push(Diagnostic::new(DiagnosticCode::InvalidEncoding, field));
+                    continue;
+                }
+            };
+            parsed.insert(name, value);
+        }
+        if diagnostics.is_empty() {
+            Ok(Self { values: parsed })
+        } else {
+            Err(ConfigError::from_diagnostics(diagnostics))
+        }
+    }
+
+    pub(crate) fn values(&self) -> &BTreeMap<String, String> {
+        &self.values
+    }
+
+    pub(crate) fn retain_for_migrator(mut self) -> Self {
+        self.values
+            .retain(|name, _| name.starts_with("POSTGRES_") || name.starts_with("CRANK_DATABASE_"));
+        self
+    }
+}
@@ -0,0 +1,42 @@
+pub(crate) fn valid_percent_encoding(value: &str) -> bool {
+    let bytes = value.as_bytes();
+    let mut index = 0;
+    while index < bytes.len() {
+        if bytes[index] == b'%' {
+            if index + 2 >= bytes.len()
+                || !bytes[index + 1].is_ascii_hexdigit()
+                || !bytes[index + 2].is_ascii_hexdigit()
+            {
+                return false;
+            }
+            index += 3;
+        } else {
+            index += 1;
+        }
+    }
+    true
+}
+
+pub(crate) fn valid_database_host(value: &str) -> bool {
+    !value.is_empty()
+        && value.len() <= 253
+        && !value.chars().any(char::is_whitespace)
+        && (value.parse::<std::net::IpAddr>().is_ok()
+            || value.split('.').all(|label| {
+                !label.is_empty()
+                    && label.len() <= 63
+                    && label
+                        .bytes()
+                        .all(|byte| byte.is_ascii_alphanumeric() || byte == b'-')
+                    && !label.starts_with('-')
+                    && !label.ends_with('-')
+            }))
+}
+
+pub(crate) fn valid_database_identifier(value: &str) -> bool {
+    !value.is_empty()
+        && value.len() <= 128
+        && value
+            .bytes()
+            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'-' | b'.'))
+}
@@ -0,0 +1,42 @@
+use std::fmt;
+
+#[derive(Clone, Eq, PartialEq)]
+pub struct SecretString(String);
+
+impl SecretString {
+    pub(crate) fn new(value: String) -> Self {
+        Self(value)
+    }
+
+    /// Deliberate composition boundary. Never use in diagnostics or fingerprints.
+    pub fn expose_secret(&self) -> &str {
+        &self.0
+    }
+
+    pub fn is_configured(&self) -> bool {
+        !self.0.is_empty()
+    }
+}
+
+impl fmt::Debug for SecretString {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_tuple("SecretString")
+            .field(&if self.is_configured() {
+                "configured"
+            } else {
+                "unconfigured"
+            })
+            .finish()
+    }
+}
+
+impl fmt::Display for SecretString {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str(if self.is_configured() {
+            "configured"
+        } else {
+            "unconfigured"
+        })
+    }
+}
@@ -0,0 +1,558 @@
+use std::collections::BTreeMap;
+
+use crank_config::{
+    ConfigSource, DiagnosticCode, FieldMode, ProcessKind, ProcessScope, field_registry,
+    parse_migrator, parse_process,
+};
+
+fn required_admin() -> BTreeMap<String, String> {
+    [
+        ("CRANK_MASTER_KEY", "master"),
+        ("CRANK_SESSION_SECRET", "session"),
+        ("CRANK_PASSWORD_PEPPER", "pepper"),
+        ("CRANK_BOOTSTRAP_ADMIN_EMAIL", "owner@example.test"),
+        ("CRANK_BOOTSTRAP_ADMIN_PASSWORD", "password"),
+    ]
+    .into_iter()
+    .map(|(key, value)| (key.to_owned(), value.to_owned()))
+    .collect()
+}
+
+fn required_mcp() -> BTreeMap<String, String> {
+    [("CRANK_MASTER_KEY", "master")]
+        .into_iter()
+        .map(|(key, value)| (key.to_owned(), value.to_owned()))
+        .collect()
+}
+
+#[test]
+fn migrator_projection_requires_only_database_configuration() {
+    let config = parse_migrator(ConfigSource::from_utf8(BTreeMap::new()))
+        .expect("database defaults are sufficient for the controlled migration job");
+    assert_eq!(config.database.host, "postgres");
+    assert_eq!(config.database.port, 5432);
+    assert_eq!(config.fingerprint().len(), 64);
+    let debug = format!("{config:?}");
+    assert!(
+        !debug.contains("crank"),
+        "database password must remain redacted"
+    );
+}
+
+#[test]
+fn migrator_ignores_service_configuration_and_rejects_database_typos() {
+    let mut values = BTreeMap::from([
+        ("CRANK_MASTER_KEY".to_owned(), "secret-canary".to_owned()),
+        (
+            "CRANK_SESSION_SECRET".to_owned(),
+            "secret-canary".to_owned(),
+        ),
+        ("CRANK_MCP_REFRESH_MS".to_owned(), "invalid".to_owned()),
+    ]);
+    parse_migrator(ConfigSource::from_utf8(values.clone()))
+        .expect("service fields are outside the database-only projection");
+    values.insert("POSTGRES_PORRT".to_owned(), "5432".to_owned());
+    let error = parse_migrator(ConfigSource::from_utf8(values)).unwrap_err();
+    assert!(
+        error
+            .diagnostics()
+            .iter()
+            .any(|diagnostic| diagnostic.code == DiagnosticCode::UnknownField)
+    );
+    assert!(!error.to_string().contains("secret-canary"));
+}
+
+fn source_for(
+    field: &crank_config::FieldSpec,
+    value: String,
+) -> (ProcessKind, BTreeMap<String, String>) {
+    let kind = match field.process {
+        ProcessScope::McpServer => ProcessKind::McpServer,
+        ProcessScope::Shared | ProcessScope::AdminApi => ProcessKind::AdminApi,
+    };
+    let mut vars = match kind {
+        ProcessKind::AdminApi => required_admin(),
+        ProcessKind::McpServer => required_mcp(),
+    };
+    vars.insert(field.env_name.to_owned(), value);
+    match field.env_name {
+        "POSTGRES_MAX_CONNECTIONS" => {
+            vars.insert("POSTGRES_MIN_CONNECTIONS".into(), "0".into());
+        }
+        "POSTGRES_MIN_CONNECTIONS" => {
+            vars.insert("POSTGRES_MAX_CONNECTIONS".into(), "1024".into());
+        }
+        "CRANK_ADMIN_RATE_LIMIT_RPS" => {
+            vars.insert("CRANK_ADMIN_RATE_LIMIT_BURST".into(), "1000000".into());
+        }
+        "CRANK_ADMIN_RATE_LIMIT_BURST" => {
+            vars.insert("CRANK_ADMIN_RATE_LIMIT_RPS".into(), "1".into());
+        }
+        "CRANK_MCP_RATE_LIMIT_RPS" => {
+            vars.insert("CRANK_MCP_RATE_LIMIT_BURST".into(), "1000000".into());
+        }
+        "CRANK_MCP_RATE_LIMIT_BURST" => {
+            vars.insert("CRANK_MCP_RATE_LIMIT_RPS".into(), "1".into());
+        }
+        "OTEL_BSP_MAX_QUEUE_SIZE" => {
+            vars.insert("OTEL_BSP_MAX_EXPORT_BATCH_SIZE".into(), "1".into());
+        }
+        "OTEL_BSP_MAX_EXPORT_BATCH_SIZE" => {
+            vars.insert("OTEL_BSP_MAX_QUEUE_SIZE".into(), "65536".into());
+        }
+        _ => {}
+    }
+    (kind, vars)
+}
+
+#[test]
+fn registry_covers_exactly_the_57_observed_runtime_names() {
+    let registry = field_registry();
+    assert_eq!(registry.len(), 57);
+    let unique = registry
+        .iter()
+        .map(|field| field.env_name)
+        .collect::<std::collections::BTreeSet<_>>();
+    assert_eq!(unique.len(), registry.len());
+    assert!(!unique.contains("CRANK_RUNTIME_MAX_CONCURRENT_WINDOW"));
+    assert!(!unique.contains("CRANK_RUNTIME_MAX_CONCURRENT_JOBS"));
+    for field in registry {
+        assert!(!field.semantic_path.is_empty());
+        assert!(!field.env_name.is_empty());
+        assert!(!field.value_type.is_empty());
+        if let (Some(minimum), Some(maximum)) = (field.minimum, field.maximum) {
+            assert!(minimum <= maximum, "{}", field.env_name);
+        }
+    }
+    assert_eq!(
+        registry
+            .iter()
+            .find(|field| field.env_name == "CRANK_CACHE_DEFAULT_TTL_MS")
+            .unwrap()
+            .mode,
+        FieldMode::DeprecatedNoEffect
+    );
+}
+
+#[test]
+fn defaults_are_preserved_and_invalid_values_never_fall_back() {
+    let valid = parse_process(
+        ProcessKind::AdminApi,
+        ConfigSource::from_utf8(required_admin()),
+    )
+    .expect("minimal admin config");
+    let admin = valid.admin().expect("admin projection");
+    assert_eq!(admin.database.port, 5432);
+    assert_eq!(admin.session_ttl_hours, 24);
+    assert_eq!(admin.rate_limit.requests_per_second, 30);
+
+    for (name, value) in [
+        ("POSTGRES_PORT", "bad"),
+        ("CRANK_SESSION_TTL_HOURS", "bad"),
+        ("CRANK_ADMIN_RATE_LIMIT_RPS", "bad"),
+        ("CRANK_TRUST_FORWARDED_HEADERS", "tru"),
+    ] {
+        let mut vars = required_admin();
+        vars.insert(name.to_owned(), value.to_owned());
+        let error =
+            parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).unwrap_err();
+        let path = field_registry()
+            .iter()
+            .find(|field| field.env_name == name)
+            .unwrap()
+            .semantic_path;
+        assert!(error.diagnostics().iter().any(|item| item.field == path));
+    }
+}
+
+#[test]
+fn database_forms_conflict_and_owned_typos_fail_closed() {
+    let mut vars = required_admin();
+    vars.insert(
+        "CRANK_DATABASE_URL".into(),
+        "postgres://user:secret@db/crank".into(),
+    );
+    vars.insert("POSTGRES_HOST".into(), "db".into());
+    let error = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).unwrap_err();
+    assert!(
+        error
+            .diagnostics()
+            .iter()
+            .any(|item| item.code == DiagnosticCode::Conflict)
+    );
+
+    let mut vars = required_admin();
+    vars.insert("CRANK_SESION_SECRET".into(), "canary".into());
+    let error = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).unwrap_err();
+    assert!(
+        error
+            .diagnostics()
+            .iter()
+            .any(|item| item.code == DiagnosticCode::UnknownField)
+    );
+    assert!(!error.to_string().contains("canary"));
+
+    for ghost in [
+        "CRANK_RUNTIME_MAX_CONCURRENT_WINDOW",
+        "CRANK_RUNTIME_MAX_CONCURRENT_JOBS",
+    ] {
+        let mut vars = required_admin();
+        vars.insert(ghost.into(), "4".into());
+        let error =
+            parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).unwrap_err();
+        assert!(error.diagnostics().iter().any(|item| {
+            item.code == DiagnosticCode::UnknownField && item.field == "environment.unknown"
+        }));
+    }
+}
+
+#[test]
+fn exact_deployment_only_names_are_known_but_never_runtime_fields() {
+    let mut vars = required_admin();
+    for name in crank_config::deployment_field_registry() {
+        vars.insert((*name).to_owned(), "deployment-value".to_owned());
+    }
+    let config = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).unwrap();
+    assert!(config.admin().is_some());
+    assert!(
+        field_registry()
+            .iter()
+            .all(|field| { !crank_config::deployment_field_registry().contains(&field.env_name) })
+    );
+}
+
+#[test]
+fn parsed_but_unused_cache_ttl_is_an_explicit_non_pass_contract() {
+    let mut vars = required_admin();
+    vars.insert("CRANK_CACHE_DEFAULT_TTL_MS".into(), "5000".into());
+    let error = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).unwrap_err();
+    assert!(error.diagnostics().iter().any(|item| {
+        item.code == DiagnosticCode::DeprecatedNoEffect && item.field == "cache.default_ttl_ms"
+    }));
+}
+
+#[cfg(unix)]
+#[test]
+fn os_source_rejects_non_utf8_without_echoing_bytes() {
+    use std::{ffi::OsString, os::unix::ffi::OsStringExt};
+
+    let error = ConfigSource::from_os_iter([(
+        OsString::from("CRANK_MASTER_KEY"),
+        OsString::from_vec(vec![0xff, b'S', b'E', b'C', b'R', b'E', b'T']),
+    )])
+    .unwrap_err();
+    assert!(
+        error
+            .diagnostics()
+            .iter()
+            .any(|item| item.code == DiagnosticCode::InvalidEncoding)
+    );
+    assert!(!error.to_string().contains("SECRET"));
+}
+
+#[cfg(unix)]
+#[test]
+fn os_source_ignores_unrelated_invalid_or_unbounded_values() {
+    use std::{ffi::OsString, os::unix::ffi::OsStringExt};
+
+    ConfigSource::from_os_iter([
+        (
+            OsString::from_vec(vec![0xff]),
+            OsString::from_vec(vec![0xff]),
+        ),
+        (
+            OsString::from("JAVA_TOOL_OPTIONS"),
+            OsString::from("x".repeat(20_000)),
+        ),
+        (OsString::from("LANG"), OsString::from_vec(vec![0xff, b'x'])),
+    ])
+    .expect("unrelated OS state is outside the runtime contract");
+}
+
+#[test]
+fn process_specific_fields_and_zero_ports_fail_closed() {
+    let mut mcp = required_mcp();
+    mcp.insert("CRANK_SESSION_SECRET".into(), "wrong-process".into());
+    let error = parse_process(ProcessKind::McpServer, ConfigSource::from_utf8(mcp)).unwrap_err();
+    assert!(error.diagnostics().iter().any(|item| {
+        item.code == DiagnosticCode::UnknownField && item.field == "admin.session.secret"
+    }));
+
+    for (kind, name, required) in [
+        (ProcessKind::AdminApi, "CRANK_ADMIN_BIND", required_admin()),
+        (
+            ProcessKind::AdminApi,
+            "CRANK_ADMIN_METRICS_BIND",
+            required_admin(),
+        ),
+        (ProcessKind::McpServer, "CRANK_MCP_BIND", required_mcp()),
+        (
+            ProcessKind::McpServer,
+            "CRANK_MCP_METRICS_BIND",
+            required_mcp(),
+        ),
+    ] {
+        let mut vars = required;
+        vars.insert(name.into(), "127.0.0.1:0".into());
+        let error = parse_process(kind, ConfigSource::from_utf8(vars)).unwrap_err();
+        let path = field_registry()
+            .iter()
+            .find(|field| field.env_name == name)
+            .unwrap()
+            .semantic_path;
+        assert!(
+            error
+                .diagnostics()
+                .iter()
+                .any(|item| { item.code == DiagnosticCode::OutOfRange && item.field == path })
+        );
+    }
+}
+
+#[test]
+fn whitespace_secrets_and_consumer_invalid_values_fail_in_the_leaf_parser() {
+    for name in [
+        "CRANK_MASTER_KEY",
+        "CRANK_SESSION_SECRET",
+        "CRANK_PASSWORD_PEPPER",
+        "CRANK_BOOTSTRAP_ADMIN_PASSWORD",
+    ] {
+        let mut vars = required_admin();
+        vars.insert(name.into(), "   ".into());
+        assert!(
+            parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).is_err(),
+            "{name}"
+        );
+    }
+    for (name, value) in [
+        ("CRANK_OUTBOUND_ALLOWED_HOSTS", "example.test:443"),
+        ("CRANK_DATABASE_URL", "postgres://db/crank?sslmode=bogus"),
+        ("CRANK_ENVIRONMENT", "bad environment"),
+        ("CRANK_SENTRY_DSN", "not-a-dsn"),
+        ("OTEL_EXPORTER_OTLP_HEADERS", "bad name=value"),
+        (
+            "CRANK_BASE_URL",
+            "https://user:secret@example.test/path?token=x",
+        ),
+    ] {
+        let mut vars = required_admin();
+        vars.insert(name.into(), value.into());
+        let error =
+            parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).expect_err(name);
+        assert!(
+            error
+                .diagnostics()
+                .iter()
+                .any(|item| item.code == DiagnosticCode::InvalidType),
+            "{name}: {error}"
+        );
+    }
+}
+
+#[test]
+fn cross_field_and_typed_boundaries_fail_closed() {
+    let cases = [
+        ("POSTGRES_MAX_CONNECTIONS", "1025"),
+        ("CRANK_ADMIN_RATE_LIMIT_RPS", "100001"),
+        ("CRANK_ADMIN_RATE_LIMIT_BURST", "0"),
+        ("CRANK_OUTBOUND_MAX_RESPONSE_BYTES", "67108865"),
+        ("OTEL_BSP_SCHEDULE_DELAY", "bad"),
+        ("OTEL_BSP_EXPORT_TIMEOUT", "300001"),
+        ("CRANK_BASE_URL", "file:///tmp/config"),
+    ];
+    for (name, value) in cases {
+        let mut vars = required_admin();
+        vars.insert(name.to_owned(), value.to_owned());
+        let error =
+            parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).expect_err(name);
+        assert!(
+            error.diagnostics().iter().any(|item| item.field
+                == field_registry()
+                    .iter()
+                    .find(|field| field.env_name == name)
+                    .unwrap()
+                    .semantic_path),
+            "{name}: {error}"
+        );
+    }
+
+    let mut vars = required_admin();
+    vars.insert("POSTGRES_MIN_CONNECTIONS".into(), "21".into());
+    let error = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).unwrap_err();
+    assert!(
+        error
+            .diagnostics()
+            .iter()
+            .any(|item| item.code == DiagnosticCode::UnsafeCombination)
+    );
+
+    let mut vars = required_admin();
+    vars.insert("CRANK_CACHE_BACKEND".into(), "valkey".into());
+    vars.insert("CRANK_CACHE_URL".into(), "https://not-a-cache.test".into());
+    let error = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).unwrap_err();
+    assert!(
+        error
+            .diagnostics()
+            .iter()
+            .any(|item| item.field == "cache.url")
+    );
+}
+
+#[test]
+fn inclusive_edges_and_legacy_boolean_spellings_are_explicit() {
+    let mut vars = required_admin();
+    vars.extend([
+        ("POSTGRES_PORT".into(), "65535".into()),
+        ("POSTGRES_MAX_CONNECTIONS".into(), "1024".into()),
+        ("POSTGRES_MIN_CONNECTIONS".into(), "0".into()),
+        ("CRANK_RUNTIME_MAX_CONCURRENT_UNARY".into(), "1".into()),
+        (
+            "CRANK_OUTBOUND_MAX_RESPONSE_BYTES".into(),
+            "67108864".into(),
+        ),
+        ("CRANK_TRUST_FORWARDED_HEADERS".into(), "yes".into()),
+        ("CRANK_DEMO_SEED".into(), "off".into()),
+    ]);
+    let config = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).unwrap();
+    let admin = config.admin().unwrap();
+    assert_eq!(admin.database.port, 65_535);
+    assert_eq!(admin.database.pool.max_connections, 1024);
+    assert_eq!(admin.database.pool.min_connections, 0);
+    assert_eq!(admin.runtime.max_concurrent_unary, 1);
+    assert!(admin.trust_forwarded_headers);
+    assert!(!admin.demo_seed);
+}
+
+#[test]
+fn admin_and_mcp_share_one_normalized_foundation() {
+    let mut vars = required_admin();
+    vars.extend([
+        ("CRANK_BASE_URL".into(), "https://crank.example.test".into()),
+        ("CRANK_RUNTIME_MAX_CONCURRENT_UNARY".into(), "72".into()),
+        (
+            "CRANK_OUTBOUND_ALLOWED_HOSTS".into(),
+            "api.example.test".into(),
+        ),
+        ("POSTGRES_MAX_CONNECTIONS".into(), "24".into()),
+    ]);
+    let admin =
+        parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars.clone())).unwrap();
+    let mut mcp_vars = vars;
+    for key in [
+        "CRANK_SESSION_SECRET",
+        "CRANK_PASSWORD_PEPPER",
+        "CRANK_BOOTSTRAP_ADMIN_EMAIL",
+        "CRANK_BOOTSTRAP_ADMIN_PASSWORD",
+    ] {
+        mcp_vars.remove(key);
+    }
+    let mcp = parse_process(ProcessKind::McpServer, ConfigSource::from_utf8(mcp_vars)).unwrap();
+    let admin = admin.admin().unwrap();
+    let mcp = mcp.mcp().unwrap();
+    assert_eq!(admin.database.host, mcp.database.host);
+    assert_eq!(
+        admin.database.pool.max_connections,
+        mcp.database.pool.max_connections
+    );
+    assert_eq!(admin.runtime.base_url, mcp.runtime.base_url);
+    assert_eq!(
+        admin.runtime.max_concurrent_unary,
+        mcp.runtime.max_concurrent_unary
+    );
+    assert_eq!(
+        admin.runtime.outbound.allowed_hosts,
+        mcp.runtime.outbound.allowed_hosts
+    );
+}
+
+#[test]
+fn every_bounded_numeric_field_accepts_edges_and_rejects_outside_values() {
+    for field in field_registry().iter().filter(|field| {
+        field.mode == FieldMode::Effective && field.minimum.is_some() && field.maximum.is_some()
+    }) {
+        let minimum = field.minimum.unwrap();
+        let maximum = field.maximum.unwrap();
+        for accepted in [minimum, maximum] {
+            let (kind, vars) = source_for(field, accepted.to_string());
+            parse_process(kind, ConfigSource::from_utf8(vars))
+                .unwrap_or_else(|error| panic!("{}={accepted}: {error}", field.env_name));
+        }
+        for rejected in [
+            if minimum == 0 {
+                "-1".to_owned()
+            } else {
+                (minimum - 1).to_string()
+            },
+            (maximum + 1).to_string(),
+        ] {
+            let (kind, vars) = source_for(field, rejected);
+            let error =
+                parse_process(kind, ConfigSource::from_utf8(vars)).expect_err(field.env_name);
+            assert!(
+                error
+                    .diagnostics()
+                    .iter()
+                    .any(|item| item.field == field.semantic_path),
+                "{}: {error}",
+                field.env_name
+            );
+        }
+
+        for malformed in ["-1", "184467440737095516160", "1.5", " 1", "1\n"] {
+            let (kind, vars) = source_for(field, malformed.to_owned());
+            let error =
+                parse_process(kind, ConfigSource::from_utf8(vars)).expect_err(field.env_name);
+            assert!(
+                error
+                    .diagnostics()
+                    .iter()
+                    .any(|item| item.field == field.semantic_path),
+                "{}={malformed:?}: {error}",
+                field.env_name
+            );
+        }
+    }
+}
+
+#[test]
+fn compatibility_values_and_otel_precedence_remain_explicit() {
+    let mut vars = required_admin();
+    vars.extend([
+        ("CRANK_CACHE_BACKEND".into(), "redis".into()),
+        (
+            "CRANK_CACHE_URL".into(),
+            "redis://cache.example.test:6379".into(),
+        ),
+        (
+            "OTEL_EXPORTER_OTLP_ENDPOINT".into(),
+            "https://generic.example.test".into(),
+        ),
+        (
+            "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT".into(),
+            "https://traces.example.test".into(),
+        ),
+        ("OTEL_EXPORTER_OTLP_TIMEOUT".into(), "10000".into()),
+        ("OTEL_EXPORTER_OTLP_TRACES_TIMEOUT".into(), "5000".into()),
+    ]);
+    let config = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).unwrap();
+    let admin = config.admin().unwrap();
+    assert_eq!(
+        admin.runtime.cache.backend,
+        crank_config::CacheBackend::Redis
+    );
+    assert_eq!(
+        admin.observability.otlp.endpoint.as_deref(),
+        Some("https://generic.example.test")
+    );
+    assert_eq!(
+        admin.observability.otlp.traces_endpoint.as_deref(),
+        Some("https://traces.example.test")
+    );
+    assert_eq!(admin.observability.otlp.timeout.as_deref(), Some("10000"));
+    assert_eq!(
+        admin.observability.otlp.traces_timeout.as_deref(),
+        Some("5000")
+    );
+    assert_eq!(config.deprecations().len(), 1);
+    assert_eq!(config.deprecations()[0].field, "cache.backend");
+}
@@ -0,0 +1,48 @@
+use crank_config::{field_registry, render};
+
+#[test]
+fn generated_contract_is_deterministic_complete_and_redacted() {
+    assert_eq!(render::schema_json(), render::schema_json());
+    let schema: serde_json::Value = serde_json::from_str(&render::schema_json()).unwrap();
+    assert_eq!(
+        schema["fields"].as_array().unwrap().len(),
+        field_registry().len()
+    );
+    for section in [render::env_section(false), render::env_section(true)] {
+        assert!(!section.contains("change-me"));
+        assert!(!section.contains("CRANK_RUNTIME_MAX_CONCURRENT_WINDOW"));
+        assert!(!section.contains("CRANK_RUNTIME_MAX_CONCURRENT_JOBS"));
+        assert!(!section.contains("CRANK_CACHE_DEFAULT_TTL_MS"));
+    }
+}
+
+#[test]
+fn generated_reference_distinguishes_required_and_optional_fields() {
+    let reference = render::reference_section();
+
+    assert!(reference.contains(
+        "| `CRANK_MASTER_KEY` | `runtime.master_key` | `Shared` | `secret/-` | `required/blank` |"
+    ));
+    assert!(
+        reference
+            .contains("| `CRANK_DATABASE_URL` | `database.url` | `Shared` | `url/-` | `blank` |")
+    );
+    assert!(reference.contains(
+        "| `CRANK_LOG_LEVEL` | `observability.log_filter` | `Shared` | `string/-` | `blank` |"
+    ));
+}
+
+#[test]
+fn marker_replacement_is_bounded_to_the_generated_region() {
+    let input = "before\n# BEGIN GENERATED CRANK RUNTIME CONFIG\nstale\n# END GENERATED CRANK RUNTIME CONFIG\nafter\n";
+    let output = render::replace_marked(
+        input,
+        render::BEGIN_MARKER,
+        render::END_MARKER,
+        &render::env_section(false),
+    )
+    .unwrap();
+    assert!(output.starts_with("before\n"));
+    assert!(output.ends_with("\nafter\n"));
+    assert!(!output.contains("stale"));
+}
@@ -0,0 +1,178 @@
+use std::collections::BTreeMap;
+
+use crank_config::{ConfigSource, ProcessKind, parse_process};
+
+fn config(secret: &str) -> crank_config::EffectiveConfig {
+    let vars = [
+        ("CRANK_MASTER_KEY", secret),
+        ("CRANK_SESSION_SECRET", secret),
+        ("CRANK_PASSWORD_PEPPER", secret),
+        ("CRANK_BOOTSTRAP_ADMIN_EMAIL", "owner@example.test"),
+        ("CRANK_BOOTSTRAP_ADMIN_PASSWORD", secret),
+    ]
+    .into_iter()
+    .map(|(key, value)| (key.to_owned(), value.to_owned()))
+    .collect::<BTreeMap<_, _>>();
+    parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).unwrap()
+}
+
+#[test]
+fn secrets_are_absent_from_debug_display_and_fingerprint() {
+    let first = config("CANARY_ONE");
+    let second = config("CANARY_TWO");
+    let rendered = format!("{first:?}");
+    assert!(!rendered.contains("CANARY_ONE"));
+    assert_eq!(first.fingerprint(), second.fingerprint());
+    assert_eq!(first.fingerprint().len(), 64);
+    assert!(
+        first
+            .fingerprint()
+            .bytes()
+            .all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase())
+    );
+}
+
+#[test]
+fn effective_semantics_not_input_spelling_drive_fingerprint() {
+    let mut canonical = [
+        ("CRANK_MASTER_KEY", "master"),
+        ("CRANK_SESSION_SECRET", "session"),
+        ("CRANK_PASSWORD_PEPPER", "pepper"),
+        ("CRANK_BOOTSTRAP_ADMIN_EMAIL", "owner@example.test"),
+        ("CRANK_BOOTSTRAP_ADMIN_PASSWORD", "password"),
+        ("CRANK_TRUST_FORWARDED_HEADERS", "true"),
+    ]
+    .into_iter()
+    .map(|(key, value)| (key.to_owned(), value.to_owned()))
+    .collect::<BTreeMap<_, _>>();
+    let mut compatibility = canonical.clone();
+    compatibility.insert("CRANK_TRUST_FORWARDED_HEADERS".into(), "yes".into());
+
+    let canonical_config = parse_process(
+        ProcessKind::AdminApi,
+        ConfigSource::from_utf8(canonical.clone()),
+    )
+    .unwrap();
+    let compatibility_config = parse_process(
+        ProcessKind::AdminApi,
+        ConfigSource::from_utf8(compatibility),
+    )
+    .unwrap();
+    assert_eq!(
+        canonical_config.fingerprint(),
+        compatibility_config.fingerprint()
+    );
+    assert_eq!(compatibility_config.deprecations().len(), 1);
+
+    canonical.insert("CRANK_SESSION_TTL_HOURS".into(), "48".into());
+    let changed = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(canonical)).unwrap();
+    assert_ne!(changed.fingerprint(), compatibility_config.fingerprint());
+}
+
+#[test]
+fn diagnostics_are_bounded_json_and_never_echo_secret_canaries() {
+    let canary = "CANARY_SECRET_VALUE";
+    let vars = [
+        ("CRANK_MASTER_KEY", canary),
+        ("CRANK_SESSION_SECRET", canary),
+        ("CRANK_PASSWORD_PEPPER", canary),
+        ("CRANK_BOOTSTRAP_ADMIN_EMAIL", "owner@example.test"),
+        ("CRANK_BOOTSTRAP_ADMIN_PASSWORD", canary),
+        (
+            "CRANK_DATABASE_URL",
+            "postgres://owner:CANARY_SECRET_VALUE@db/crank",
+        ),
+        ("POSTGRES_PASSWORD", canary),
+        ("CRANK_CACHE_BACKEND", "memory"),
+        ("CRANK_CACHE_URL", "redis://:CANARY_SECRET_VALUE@cache:6379"),
+        (
+            "CRANK_SENTRY_DSN",
+            "https://CANARY_SECRET_VALUE@sentry.test/1",
+        ),
+        ("CRANK_METRICS_BEARER_TOKEN", canary),
+        (
+            "OTEL_EXPORTER_OTLP_HEADERS",
+            "authorization=CANARY_SECRET_VALUE",
+        ),
+    ]
+    .into_iter()
+    .map(|(key, value)| (key.to_owned(), value.to_owned()))
+    .collect::<BTreeMap<_, _>>();
+    let error = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).unwrap_err();
+    let display = error.to_string();
+    let json = error.to_json();
+    assert!(json.len() <= 65_536);
+    assert!(serde_json::from_str::<serde_json::Value>(&json).is_ok());
+    assert!(!display.contains(canary));
+    assert!(!json.contains(canary));
+    assert!(error.diagnostics().len() <= 100);
+}
+
+#[test]
+fn public_projection_debug_omits_urls_hosts_paths_and_identity_values() {
+    let mut vars = [
+        ("CRANK_MASTER_KEY", "master"),
+        ("CRANK_SESSION_SECRET", "session"),
+        ("CRANK_PASSWORD_PEPPER", "pepper"),
+        ("CRANK_BOOTSTRAP_ADMIN_EMAIL", "owner@CANARY.test"),
+        ("CRANK_BOOTSTRAP_ADMIN_PASSWORD", "password"),
+        ("CRANK_STORAGE_ROOT", "/CANARY/private/storage"),
+        ("POSTGRES_HOST", "CANARY-db.internal"),
+        ("CRANK_OUTBOUND_ALLOWED_HOSTS", "CANARY-api.internal"),
+    ]
+    .into_iter()
+    .map(|(k, v)| (k.to_owned(), v.to_owned()))
+    .collect::<BTreeMap<_, _>>();
+    vars.insert(
+        "CRANK_BASE_URL".into(),
+        "https://CANARY.example.test".into(),
+    );
+    let config = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(vars)).unwrap();
+    let rendered = format!("{:?}", config.admin().unwrap());
+    assert!(!rendered.contains("CANARY"), "{rendered}");
+}
+
+#[test]
+fn normalized_database_and_admin_default_urls_drive_fingerprint() {
+    let base = [
+        ("CRANK_MASTER_KEY", "master"),
+        ("CRANK_SESSION_SECRET", "session"),
+        ("CRANK_PASSWORD_PEPPER", "pepper"),
+        ("CRANK_BOOTSTRAP_ADMIN_EMAIL", "owner@example.test"),
+        ("CRANK_BOOTSTRAP_ADMIN_PASSWORD", "password"),
+    ]
+    .into_iter()
+    .map(|(k, v)| (k.to_owned(), v.to_owned()))
+    .collect::<BTreeMap<_, _>>();
+    let implicit =
+        parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(base.clone())).unwrap();
+    let mut explicit = base.clone();
+    explicit.insert("CRANK_BASE_URL".into(), "http://localhost:3000".into());
+    let explicit = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(explicit)).unwrap();
+    assert_eq!(implicit.fingerprint(), explicit.fingerprint());
+
+    let mut url = base;
+    url.insert(
+        "CRANK_DATABASE_URL".into(),
+        "postgres://crank:rotated@postgres/crank".into(),
+    );
+    let url = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(url)).unwrap();
+    assert_eq!(implicit.fingerprint(), url.fingerprint());
+
+    let tls = [
+        ("CRANK_MASTER_KEY", "master"),
+        ("CRANK_SESSION_SECRET", "session"),
+        ("CRANK_PASSWORD_PEPPER", "pepper"),
+        ("CRANK_BOOTSTRAP_ADMIN_EMAIL", "owner@example.test"),
+        ("CRANK_BOOTSTRAP_ADMIN_PASSWORD", "password"),
+        (
+            "CRANK_DATABASE_URL",
+            "postgres://crank:rotated@postgres/crank?sslmode=require",
+        ),
+    ]
+    .into_iter()
+    .map(|(k, v)| (k.to_owned(), v.to_owned()))
+    .collect::<BTreeMap<_, _>>();
+    let tls = parse_process(ProcessKind::AdminApi, ConfigSource::from_utf8(tls)).unwrap();
+    assert_ne!(implicit.fingerprint(), tls.fingerprint());
+}
@@ -12,6 +12,7 @@ serde.workspace = true
 serde_json.workspace = true
 thiserror.workspace = true
 time.workspace = true
+uuid.workspace = true

 [dev-dependencies]
 serde_yaml.workspace = true
@@ -0,0 +1,275 @@
+use serde::{Deserialize, Deserializer, Serialize, de};
+use uuid::Uuid;
+
+const TRACEPARENT_VERSION: &str = "00";
+const ZERO_TRACE_ID: &str = "00000000000000000000000000000000";
+const ZERO_PARENT_ID: &str = "0000000000000000";
+
+#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize)]
+#[serde(transparent)]
+pub struct RequestId(String);
+
+impl RequestId {
+    pub const MAX_LEN: usize = 128;
+
+    pub fn generate() -> Self {
+        Self(Uuid::now_v7().to_string())
+    }
+
+    pub fn resolve(candidate: Option<&str>) -> Self {
+        candidate
+            .filter(|value| Self::is_valid(value))
+            .map(|value| Self(value.to_owned()))
+            .unwrap_or_else(Self::generate)
+    }
+
+    pub fn parse(value: &str) -> Result<Self, CorrelationError> {
+        Self::is_valid(value)
+            .then(|| Self(value.to_owned()))
+            .ok_or(CorrelationError::InvalidRequestId)
+    }
+
+    pub fn is_valid(value: &str) -> bool {
+        !value.is_empty()
+            && value.len() <= Self::MAX_LEN
+            && value
+                .bytes()
+                .all(|byte| byte.is_ascii_graphic() && byte != b',' && byte != b';')
+    }
+
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+
+impl std::fmt::Display for RequestId {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter.write_str(&self.0)
+    }
+}
+
+impl<'de> Deserialize<'de> for RequestId {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        let value = String::deserialize(deserializer)?;
+        Self::parse(&value).map_err(de::Error::custom)
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize)]
+#[serde(transparent)]
+pub struct TraceId(String);
+
+impl TraceId {
+    pub const LEN: usize = 32;
+
+    pub fn generate() -> Self {
+        let value = Uuid::now_v7().simple().to_string();
+        debug_assert_ne!(value, ZERO_TRACE_ID);
+        Self(value)
+    }
+
+    pub fn parse(value: &str) -> Result<Self, CorrelationError> {
+        if is_lower_hex(value, Self::LEN) && value != ZERO_TRACE_ID {
+            Ok(Self(value.to_owned()))
+        } else {
+            Err(CorrelationError::InvalidTraceId)
+        }
+    }
+
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+
+impl std::fmt::Display for TraceId {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter.write_str(&self.0)
+    }
+}
+
+impl<'de> Deserialize<'de> for TraceId {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        let value = String::deserialize(deserializer)?;
+        Self::parse(&value).map_err(de::Error::custom)
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
+pub struct TraceContext {
+    trace_id: TraceId,
+    traceparent: String,
+}
+
+impl TraceContext {
+    pub const TRACEPARENT_LEN: usize = 55;
+    pub const TRACESTATE_MAX_BYTES: usize = 512;
+    pub const TRACESTATE_MAX_MEMBERS: usize = 32;
+    pub const BAGGAGE_MAX_BYTES: usize = 8_192;
+    pub const BAGGAGE_MAX_MEMBERS: usize = 64;
+
+    pub fn generate() -> Self {
+        let trace_id = TraceId::generate();
+        let mut parent_id = Uuid::now_v7().simple().to_string()[..16].to_owned();
+        if parent_id == ZERO_PARENT_ID {
+            parent_id.replace_range(15..16, "1");
+        }
+        // A context generated outside an SDK span must not claim that a sampler
+        // selected it. Ingress replaces this seed with the actual local span
+        // context before application code runs.
+        let traceparent = format!("{TRACEPARENT_VERSION}-{trace_id}-{parent_id}-00");
+        Self {
+            trace_id,
+            traceparent,
+        }
+    }
+
+    pub fn parse(value: &str) -> Result<Self, CorrelationError> {
+        if value.len() != Self::TRACEPARENT_LEN {
+            return Err(CorrelationError::InvalidTraceparent);
+        }
+        let bytes = value.as_bytes();
+        if bytes[2] != b'-' || bytes[35] != b'-' || bytes[52] != b'-' {
+            return Err(CorrelationError::InvalidTraceparent);
+        }
+        let version = &value[0..2];
+        let trace_id = &value[3..35];
+        let parent_id = &value[36..52];
+        let flags = &value[53..55];
+        if version != TRACEPARENT_VERSION
+            || !is_lower_hex(parent_id, 16)
+            || parent_id == ZERO_PARENT_ID
+            || !matches!(flags, "00" | "01")
+        {
+            return Err(CorrelationError::InvalidTraceparent);
+        }
+        Ok(Self {
+            trace_id: TraceId::parse(trace_id).map_err(|_| CorrelationError::InvalidTraceparent)?,
+            traceparent: value.to_owned(),
+        })
+    }
+
+    pub fn from_span_parts(
+        trace_id: &str,
+        span_id: &str,
+        sampled: bool,
+    ) -> Result<Self, CorrelationError> {
+        let flags = if sampled { "01" } else { "00" };
+        Self::parse(&format!(
+            "{TRACEPARENT_VERSION}-{trace_id}-{span_id}-{flags}"
+        ))
+    }
+
+    pub fn continue_local(&self) -> Self {
+        let mut span_id = Uuid::now_v7().simple().to_string()[..16].to_owned();
+        if span_id == ZERO_PARENT_ID {
+            span_id.replace_range(15..16, "1");
+        }
+        let sampled = self.traceparent.ends_with("-01");
+        Self::from_span_parts(self.trace_id.as_str(), &span_id, sampled)
+            .expect("generated span identity is canonical")
+    }
+
+    pub fn trace_id(&self) -> &TraceId {
+        &self.trace_id
+    }
+
+    pub fn traceparent(&self) -> &str {
+        &self.traceparent
+    }
+
+    pub fn tracestate_within_budget(value: &str) -> bool {
+        header_list_within_budget(
+            value,
+            Self::TRACESTATE_MAX_BYTES,
+            Self::TRACESTATE_MAX_MEMBERS,
+        )
+    }
+
+    pub fn baggage_within_budget(value: &str) -> bool {
+        header_list_within_budget(value, Self::BAGGAGE_MAX_BYTES, Self::BAGGAGE_MAX_MEMBERS)
+    }
+}
+
+impl<'de> Deserialize<'de> for TraceContext {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        #[derive(Deserialize)]
+        #[serde(deny_unknown_fields)]
+        struct WireTraceContext {
+            trace_id: TraceId,
+            traceparent: String,
+        }
+
+        let wire = WireTraceContext::deserialize(deserializer)?;
+        let context = Self::parse(&wire.traceparent).map_err(de::Error::custom)?;
+        if context.trace_id != wire.trace_id {
+            return Err(de::Error::custom(CorrelationError::InvalidTraceparent));
+        }
+        Ok(context)
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct CorrelationContext {
+    request_id: RequestId,
+    trace_context: TraceContext,
+}
+
+impl CorrelationContext {
+    pub fn new(request_id: RequestId, trace_context: TraceContext) -> Self {
+        Self {
+            request_id,
+            trace_context,
+        }
+    }
+
+    pub fn generate() -> Self {
+        Self::new(RequestId::generate(), TraceContext::generate())
+    }
+
+    pub fn request_id(&self) -> &RequestId {
+        &self.request_id
+    }
+
+    pub fn trace_context(&self) -> &TraceContext {
+        &self.trace_context
+    }
+
+    pub fn trace_id(&self) -> &TraceId {
+        self.trace_context.trace_id()
+    }
+}
+
+#[derive(Clone, Copy, Debug, thiserror::Error, PartialEq, Eq)]
+pub enum CorrelationError {
+    #[error("invalid request identity")]
+    InvalidRequestId,
+    #[error("invalid trace identity")]
+    InvalidTraceId,
+    #[error("invalid trace parent")]
+    InvalidTraceparent,
+}
+
+fn is_lower_hex(value: &str, expected_len: usize) -> bool {
+    value.len() == expected_len
+        && value
+            .bytes()
+            .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
+}
+
+fn header_list_within_budget(value: &str, max_bytes: usize, max_members: usize) -> bool {
+    !value.is_empty()
+        && value.len() <= max_bytes
+        && value.is_ascii()
+        && !value.bytes().any(|byte| byte.is_ascii_control())
+        && value.split(',').count() <= max_members
+        && value.split(',').all(|member| !member.trim().is_empty())
+}
@@ -4,7 +4,10 @@ use async_trait::async_trait;
 use serde::{Deserialize, Serialize};
 use serde_json::Value;

-use crate::{AgentId, InvocationSource, Protocol, Target, WorkspaceId};
+use crate::{
+    AgentId, CorrelationContext, InvocationSource, Protocol, RequestId, Target, TraceContext,
+    WorkspaceId,
+};

 #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
@@ -20,8 +23,8 @@ pub struct ResponseCacheScope {

 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct RuntimeRequestContext {
-    pub request_id: String,
-    pub correlation_id: String,
+    pub request_id: RequestId,
+    pub trace_context: TraceContext,
    pub response_cache_scope: Option<ResponseCacheScope>,
    pub metering_context: Option<MeteringContext>,
 }
@@ -34,10 +37,10 @@ pub struct MeteringContext {
 }

 impl RuntimeRequestContext {
-    pub fn new(request_id: impl Into<String>, correlation_id: impl Into<String>) -> Self {
+    pub fn new(request_id: RequestId, trace_context: TraceContext) -> Self {
        Self {
-            request_id: request_id.into(),
-            correlation_id: correlation_id.into(),
+            request_id,
+            trace_context,
            response_cache_scope: None,
            metering_context: None,
        }
@@ -45,13 +48,33 @@ impl RuntimeRequestContext {

    pub fn from_request_id(request_id: impl Into<String>) -> Self {
        let request_id = request_id.into();
-        Self::new(request_id.clone(), request_id)
+        Self::new(
+            RequestId::resolve(Some(&request_id)),
+            TraceContext::generate(),
+        )
+    }
+
+    pub fn from_correlation(context: &CorrelationContext) -> Self {
+        Self::new(
+            context.request_id().clone(),
+            context.trace_context().clone(),
+        )
    }

    pub fn outbound_headers(&self) -> BTreeMap<String, String> {
        BTreeMap::from([
-            ("x-request-id".to_owned(), self.request_id.clone()),
-            ("x-correlation-id".to_owned(), self.correlation_id.clone()),
+            ("x-request-id".to_owned(), self.request_id.to_string()),
+            (
+                "x-trace-id".to_owned(),
+                self.trace_context.trace_id().to_string(),
+            ),
+            (
+                "traceparent".to_owned(),
+                self.trace_context.traceparent().to_owned(),
+            ),
+            // Compatibility alias only. It is intentionally the product Request ID,
+            // never the W3C Trace ID.
+            ("x-correlation-id".to_owned(), self.request_id.to_string()),
        ])
    }

@@ -3,6 +3,7 @@ pub mod agent;
 pub mod approval;
 pub mod auth;
 pub mod cache;
+pub mod correlation;
 pub mod edition;
 pub mod ext;
 pub mod ids;
@@ -113,6 +114,7 @@ pub use cache::{
    ParseCacheBackendError, RateLimitBucketState, RateLimitDecision, RateLimitStateStore,
    ReplayGuardStatus, ReplayGuardStore, ResponseCacheStore,
 };
+pub use correlation::{CorrelationContext, CorrelationError, RequestId, TraceContext, TraceId};
 pub use edition::{
    EditionCapabilities, EditionLimits, MachineAccessMode, OperationSecurityLevel, ProductEdition,
 };
@@ -118,6 +118,7 @@ pub struct InvocationLog {
    pub tool_name: String,
    pub message: String,
    pub request_id: Option<String>,
+    pub trace_id: Option<String>,
    pub status_code: Option<u16>,
    pub duration_ms: u64,
    pub error_kind: Option<String>,
@@ -169,6 +170,7 @@ mod tests {
            tool_name: "create_lead".to_owned(),
            message: "ok".to_owned(),
            request_id: Some("req_01".to_owned()),
+            trace_id: Some("0af7651916cd43dd8448eb211c80319c".to_owned()),
            status_code: Some(200),
            duration_ms: 123,
            error_kind: None,
@@ -0,0 +1,131 @@
+use crank_core::{CorrelationContext, RequestId, TraceContext, TraceId};
+use uuid::Version;
+
+const VALID_TRACEPARENT: &str = "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01";
+
+#[test]
+fn generated_identities_are_distinct_and_canonical() {
+    let context = CorrelationContext::generate();
+
+    assert_eq!(
+        uuid::Uuid::parse_str(context.request_id().as_str())
+            .unwrap()
+            .get_version(),
+        Some(Version::SortRand)
+    );
+    assert_eq!(context.trace_id().as_str().len(), 32);
+    assert!(
+        context
+            .trace_id()
+            .as_str()
+            .bytes()
+            .all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase())
+    );
+    assert_ne!(
+        context.request_id().as_str().replace('-', ""),
+        context.trace_id().as_str()
+    );
+}
+
+#[test]
+fn request_id_preserves_one_valid_opaque_value_and_replaces_invalid_values() {
+    assert_eq!(
+        RequestId::resolve(Some("gateway-request-42")).as_str(),
+        "gateway-request-42"
+    );
+    for invalid in ["", "bad value", "bad,value", "bad;value"] {
+        let replacement = RequestId::resolve(Some(invalid));
+        assert_ne!(replacement.as_str(), invalid);
+        assert_eq!(
+            uuid::Uuid::parse_str(replacement.as_str())
+                .unwrap()
+                .get_version(),
+            Some(Version::SortRand)
+        );
+    }
+    assert!(RequestId::is_valid(&"a".repeat(RequestId::MAX_LEN)));
+    assert!(!RequestId::is_valid(&"a".repeat(RequestId::MAX_LEN + 1)));
+}
+
+#[test]
+fn traceparent_parser_is_strict_and_never_accepts_zero_ids() {
+    let context = TraceContext::parse(VALID_TRACEPARENT).unwrap();
+    assert_eq!(
+        context.trace_id().as_str(),
+        "0af7651916cd43dd8448eb211c80319c"
+    );
+    assert_eq!(context.traceparent(), VALID_TRACEPARENT);
+
+    for invalid in [
+        "00-00000000000000000000000000000000-b7ad6b7169203331-01",
+        "00-0af7651916cd43dd8448eb211c80319c-0000000000000000-01",
+        "00-0AF7651916CD43DD8448EB211C80319C-b7ad6b7169203331-01",
+        "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-0z",
+        "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-02",
+        "ff-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
+        "canary-invalid-traceparent",
+    ] {
+        assert!(TraceContext::parse(invalid).is_err(), "accepted {invalid}");
+    }
+    assert!(TraceId::parse("00000000000000000000000000000000").is_err());
+}
+
+#[test]
+fn durable_parent_envelope_roundtrips_without_conflating_ids() {
+    let context = CorrelationContext::new(
+        RequestId::resolve(Some("request-opaque-1")),
+        TraceContext::parse(VALID_TRACEPARENT).unwrap(),
+    );
+    let encoded = serde_json::to_vec(&context).unwrap();
+    let decoded: CorrelationContext = serde_json::from_slice(&encoded).unwrap();
+
+    assert_eq!(decoded, context);
+    assert_eq!(decoded.request_id().as_str(), "request-opaque-1");
+    assert_eq!(
+        decoded.trace_id().as_str(),
+        "0af7651916cd43dd8448eb211c80319c"
+    );
+}
+
+#[test]
+fn durable_parent_envelope_rejects_invalid_or_inconsistent_identities() {
+    for candidate in [
+        serde_json::json!({
+            "request_id": "bad request",
+            "trace_context": {
+                "trace_id": "0af7651916cd43dd8448eb211c80319c",
+                "traceparent": VALID_TRACEPARENT,
+            }
+        }),
+        serde_json::json!({
+            "request_id": "request-1",
+            "trace_context": {
+                "trace_id": "00000000000000000000000000000000",
+                "traceparent": VALID_TRACEPARENT,
+            }
+        }),
+        serde_json::json!({
+            "request_id": "request-1",
+            "trace_context": {
+                "trace_id": "1af7651916cd43dd8448eb211c80319c",
+                "traceparent": VALID_TRACEPARENT,
+            }
+        }),
+    ] {
+        assert!(serde_json::from_value::<CorrelationContext>(candidate).is_err());
+    }
+}
+
+#[test]
+fn caller_state_and_baggage_budgets_are_closed_and_bounded() {
+    assert!(TraceContext::tracestate_within_budget("vendor=value"));
+    assert!(!TraceContext::tracestate_within_budget(&"x".repeat(513)));
+    assert!(!TraceContext::tracestate_within_budget(
+        &std::iter::repeat_n("a=b", 33).collect::<Vec<_>>().join(",")
+    ));
+    assert!(TraceContext::baggage_within_budget("key=value"));
+    assert!(!TraceContext::baggage_within_budget(&"x".repeat(8_193)));
+    assert!(!TraceContext::baggage_within_budget(
+        &std::iter::repeat_n("a=b", 65).collect::<Vec<_>>().join(",")
+    ));
+}
@@ -27,7 +27,6 @@ tracing.workspace = true
 tracing-opentelemetry.workspace = true
 tracing-subscriber.workspace = true
 url.workspace = true
-uuid.workspace = true

 [dev-dependencies]
 opentelemetry-proto.workspace = true
@@ -1,10 +1,8 @@
-use std::env;
-
 use thiserror::Error;
+use tracing_subscriber::EnvFilter;

 use crate::RedactionLimits;

-const DEFAULT_ENVIRONMENT: &str = "development";
 const MAX_IDENTITY_LABEL_BYTES: usize = 64;

 #[derive(Clone, Debug, Eq, PartialEq)]
@@ -52,6 +50,20 @@ pub struct ObservabilityConfig {
 }

 impl ObservabilityConfig {
+    pub fn try_new(
+        identity: ServiceIdentity,
+        filter: impl Into<String>,
+        redaction_limits: RedactionLimits,
+    ) -> Result<Self, ObservabilityConfigError> {
+        let filter = filter.into();
+        EnvFilter::try_new(&filter).map_err(|_| ObservabilityConfigError::InvalidFilter)?;
+        Ok(Self {
+            identity,
+            filter,
+            redaction_limits,
+        })
+    }
+
    pub fn new(
        identity: ServiceIdentity,
        filter: impl Into<String>,
@@ -64,26 +76,6 @@ impl ObservabilityConfig {
        }
    }

-    pub fn from_env(
-        service: &'static str,
-        version: &'static str,
-        default_filter: &'static str,
-    ) -> Result<Self, ObservabilityConfigError> {
-        let environment = env_value_or_default(
-            "CRANK_ENVIRONMENT",
-            env::var("CRANK_ENVIRONMENT"),
-            DEFAULT_ENVIRONMENT,
-        )?;
-        let filter = env_value_or_default(
-            "CRANK_LOG_LEVEL",
-            env::var("CRANK_LOG_LEVEL"),
-            default_filter,
-        )?;
-        let identity = ServiceIdentity::try_new(service, version, environment)?;
-
-        Ok(Self::new(identity, filter, RedactionLimits::default()))
-    }
-
    pub(crate) fn into_parts(self) -> (ServiceIdentity, String, RedactionLimits) {
        (self.identity, self.filter, self.redaction_limits)
    }
@@ -101,22 +93,8 @@ impl ObservabilityConfig {
 pub enum ObservabilityConfigError {
    #[error("invalid observability identity field: {field}")]
    InvalidIdentity { field: &'static str },
-    #[error("observability environment variable is not valid UTF-8: {field}")]
-    InvalidEnvironmentEncoding { field: &'static str },
-}
-
-fn env_value_or_default(
-    field: &'static str,
-    value: Result<String, env::VarError>,
-    default: &'static str,
-) -> Result<String, ObservabilityConfigError> {
-    match value {
-        Ok(value) => Ok(value),
-        Err(env::VarError::NotPresent) => Ok(default.to_owned()),
-        Err(env::VarError::NotUnicode(_)) => {
-            Err(ObservabilityConfigError::InvalidEnvironmentEncoding { field })
-        }
-    }
+    #[error("invalid observability log filter")]
+    InvalidFilter,
 }

 fn validate_label(field: &'static str, value: &str) -> Result<(), ObservabilityConfigError> {
@@ -135,9 +113,7 @@ fn validate_label(field: &'static str, value: &str) -> Result<(), ObservabilityC

 #[cfg(test)]
 mod tests {
-    use std::ffi::OsString;
-
-    use super::{ObservabilityConfigError, ServiceIdentity, env_value_or_default};
+    use super::ServiceIdentity;

    #[test]
    fn accepts_release_and_environment_labels() {
@@ -148,23 +124,4 @@ mod tests {
        assert_eq!(identity.version(), "0.3.1+build.7");
        assert_eq!(identity.environment(), "production");
    }
-
-    #[test]
-    fn rejects_non_utf8_environment_values() {
-        let error = env_value_or_default(
-            "CRANK_ENVIRONMENT",
-            Err(std::env::VarError::NotUnicode(OsString::from(
-                "invalid-environment",
-            ))),
-            "development",
-        )
-        .expect_err("non-UTF-8 values must not be replaced with defaults");
-
-        assert!(matches!(
-            error,
-            ObservabilityConfigError::InvalidEnvironmentEncoding {
-                field: "CRANK_ENVIRONMENT"
-            }
-        ));
-    }
 }
@@ -1,51 +0,0 @@
-use std::fmt;
-
-use axum::http::HeaderMap;
-use uuid::Uuid;
-
-#[derive(Clone, Debug, Eq, Hash, PartialEq)]
-pub struct RequestId(String);
-
-impl RequestId {
-    pub const MAX_LEN: usize = 128;
-    const HEADER_NAME: &'static str = "x-request-id";
-
-    pub fn resolve(candidate: Option<&str>) -> Self {
-        candidate
-            .filter(|value| Self::is_valid(value))
-            .map(|value| Self(value.to_owned()))
-            .unwrap_or_else(|| Self(Uuid::now_v7().to_string()))
-    }
-
-    pub fn resolve_from_headers(headers: &HeaderMap) -> Self {
-        let mut values = headers.get_all(Self::HEADER_NAME).iter();
-        let candidate = values.next();
-        if values.next().is_some() {
-            return Self::resolve(None);
-        }
-
-        Self::resolve(candidate.and_then(|value| value.to_str().ok()))
-    }
-
-    pub fn is_valid(value: &str) -> bool {
-        !value.is_empty()
-            && value.len() <= Self::MAX_LEN
-            && value
-                .bytes()
-                .all(|byte| matches!(byte, 0x21..=0x7e) && byte != b',' && byte != b';')
-    }
-
-    pub fn as_str(&self) -> &str {
-        &self.0
-    }
-
-    pub fn into_string(self) -> String {
-        self.0
-    }
-}
-
-impl fmt::Display for RequestId {
-    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
-        formatter.write_str(self.as_str())
-    }
-}
@@ -1,7 +1,7 @@
 use std::{
    borrow::Cow,
    collections::BTreeMap,
-    env, fmt,
+    fmt,
    future::Future,
    time::{Duration, SystemTime},
 };
@@ -13,11 +13,8 @@ use sentry::{
 };
 use thiserror::Error;

-use crate::{
-    RedactionLimits, ServiceIdentity, propagation::current_trace_id, redaction::truncate_string,
-};
+use crate::{RedactionLimits, ServiceIdentity, propagation::current_trace_id};

-const SENTRY_DSN_ENV: &str = "CRANK_SENTRY_DSN";
 const CRITICAL_ERROR_MESSAGE: &str = "critical error";
 const SENTRY_SHUTDOWN_TIMEOUT: Duration = Duration::from_secs(2);
 // Sentry serializes SystemTime as a finite f64; this keeps conservative fixed headroom.
@@ -25,6 +22,7 @@ const MAX_SERIALIZED_TIMESTAMP_BYTES: usize = 32;

 tokio::task_local! {
    static REQUEST_ID: String;
+    static TRACE_ID: String;
 }

 pub struct SentryConfig {
@@ -43,14 +41,6 @@ impl SentryConfig {
        Ok(Self { dsn: Some(dsn) })
    }

-    pub fn from_env() -> Result<Self, SentryConfigError> {
-        match env::var(SENTRY_DSN_ENV) {
-            Ok(value) => Self::parse(Some(&value)),
-            Err(env::VarError::NotPresent) => Self::parse(None),
-            Err(env::VarError::NotUnicode(_)) => Err(SentryConfigError::InvalidEnvironmentEncoding),
-        }
-    }
-
    pub fn enabled(&self) -> bool {
        self.dsn.is_some()
    }
@@ -69,8 +59,6 @@ impl fmt::Debug for SentryConfig {
 pub enum SentryConfigError {
    #[error("CRANK_SENTRY_DSN is not a valid Sentry DSN")]
    InvalidDsn,
-    #[error("CRANK_SENTRY_DSN is not valid UTF-8")]
-    InvalidEnvironmentEncoding,
    #[error("critical error event budget cannot hold the required fields")]
    EventBudgetTooSmall,
 }
@@ -123,11 +111,43 @@ pub fn capture_critical_error(category: CriticalErrorCategory) {
    });
 }

-pub async fn with_request_correlation<F>(request_id: String, future: F) -> F::Output
+pub async fn with_request_correlation<F>(
+    request_id: String,
+    trace_id: String,
+    future: F,
+) -> F::Output
 where
    F: Future,
 {
-    REQUEST_ID.scope(request_id, future).await
+    if !valid_request_id(&request_id) || !valid_trace_id(&trace_id) {
+        return future.await;
+    }
+    REQUEST_ID
+        .scope(request_id, TRACE_ID.scope(trace_id, future))
+        .await
+}
+
+fn valid_request_id(value: &str) -> bool {
+    !value.is_empty()
+        && value.len() <= 128
+        && value
+            .bytes()
+            .all(|byte| (0x21..=0x7e).contains(&byte) && byte != b',' && byte != b';')
+}
+
+fn valid_trace_id(value: &str) -> bool {
+    value.len() == 32
+        && value != "00000000000000000000000000000000"
+        && value
+            .bytes()
+            .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
+}
+
+pub fn current_request_correlation() -> (Option<String>, Option<String>) {
+    (
+        REQUEST_ID.try_with(Clone::clone).ok(),
+        TRACE_ID.try_with(Clone::clone).ok(),
+    )
 }

 pub(crate) fn init_sentry(
@@ -184,16 +204,7 @@ fn sanitize_event(
                CriticalErrorCategory::Panic
            }
        });
-    let mut tags = correlation_tags()
-        .into_iter()
-        .map(|(key, value)| (key, truncate_string(&value, limits.max_string_bytes)))
-        .collect::<BTreeMap<_, _>>();
-    for key in ["request_id", "trace_id"] {
-        if let Some(value) = event.tags.get(key) {
-            tags.entry(key.to_owned())
-                .or_insert_with(|| truncate_string(value, limits.max_string_bytes));
-        }
-    }
+    let mut tags = correlation_tags().into_iter().collect::<BTreeMap<_, _>>();
    tags.insert("service".to_owned(), identity.service().to_owned());
    tags.insert("category".to_owned(), category.as_str().to_owned());

@@ -222,19 +233,21 @@ fn correlation_tags() -> BTreeMap<String, String> {
    if let Ok(request_id) = REQUEST_ID.try_with(Clone::clone) {
        tags.insert("request_id".to_owned(), request_id);
    }
-    if let Some(trace_id) = current_trace_id() {
+    if let Ok(trace_id) = TRACE_ID.try_with(Clone::clone) {
+        tags.insert("trace_id".to_owned(), trace_id);
+    } else if let Some(trace_id) = current_trace_id() {
        tags.insert("trace_id".to_owned(), trace_id);
    }
    tags
 }

-fn enforce_event_budget(mut event: Event<'static>, max_event_bytes: usize) -> Event<'static> {
+fn enforce_event_budget(event: Event<'static>, max_event_bytes: usize) -> Event<'static> {
    if serialized_event_len(&event) <= max_event_bytes {
        return event;
    }

-    event.tags.remove("request_id");
-    event.tags.remove("trace_id");
+    // Startup validation reserves enough room for maximum canonical IDs. They
+    // are never evicted from a support event to satisfy a byte budget.
    debug_assert!(serialized_event_len(&event) <= max_event_bytes);
    event
 }
@@ -257,7 +270,7 @@ fn required_critical_event_budget(identity: &ServiceIdentity, limits: RedactionL
    CriticalErrorCategory::ALL
        .into_iter()
        .map(|category| {
-            let event = sanitize_event(
+            let mut event = sanitize_event(
                Event {
                    tags: BTreeMap::from([("category".to_owned(), category.as_str().to_owned())]),
                    timestamp: SystemTime::UNIX_EPOCH,
@@ -266,6 +279,8 @@ fn required_critical_event_budget(identity: &ServiceIdentity, limits: RedactionL
                identity,
                unbounded_limits,
            );
+            event.tags.insert("request_id".to_owned(), "r".repeat(128));
+            event.tags.insert("trace_id".to_owned(), "a".repeat(32));
            serialized_event_len(&event)
                .saturating_add(MAX_SERIALIZED_TIMESTAMP_BYTES.saturating_sub(1))
        })
@@ -439,11 +454,15 @@ mod tests {
        let events = sentry::test::with_captured_events_options(
            || {
                tracing::dispatcher::with_default(&dispatch, || {
-                    runtime.block_on(with_request_correlation("request-123".to_owned(), async {
+                    runtime.block_on(with_request_correlation(
+                        "request-123".to_owned(),
+                        "0af7651916cd43dd8448eb211c80319c".to_owned(),
+                        async {
                            let span = tracing::info_span!(target: "crank::trace", "http.request");
                            let _span_guard = span.enter();
                            capture_critical_error(CriticalErrorCategory::DataIntegrity);
-                    }));
+                        },
+                    ));
                });
            },
            options,
@@ -496,6 +515,7 @@ mod tests {
                    tracing::dispatcher::with_default(&dispatch, || {
                        runtime.block_on(with_request_correlation(
                            "panic-request-123".to_owned(),
+                            "0af7651916cd43dd8448eb211c80319c".to_owned(),
                            async {
                                let span =
                                    tracing::info_span!(target: "crank::trace", "http.request");
@@ -1,5 +1,4 @@
 mod config;
-mod correlation;
 mod error_reporting;
 mod incidents;
 mod instrumentation;
@@ -12,13 +11,12 @@ mod redaction;
 mod schema;

 pub use config::{ObservabilityConfig, ObservabilityConfigError, ServiceIdentity};
-pub use correlation::RequestId;
 pub use crank_metrics::{
    DURATION_BUCKETS_SECONDS, MetricDefinition, MetricKind, MetricUnit, metric_schema,
 };
 pub use error_reporting::{
    CriticalErrorCategory, SentryConfig, SentryConfigError, capture_critical_error,
-    with_request_correlation,
+    current_request_correlation, with_request_correlation,
 };
 pub use incidents::{OperationalIncident, operational_incident_total, record_operational_incident};
 pub use instrumentation::{record_db_pool_connections, record_http_request};
@@ -6,29 +6,45 @@ use tracing_subscriber::util::SubscriberInitExt;
 use crate::{
    MetricsConfig, MetricsSurface, MetricsSurfaceError, ObservabilityConfig,
    ObservabilityConfigError, OtlpTraceConfig, OtlpTraceConfigError, OtlpTraceError,
-    RedactionLimitsError, SentryConfig, SentryConfigError, error_reporting::init_sentry,
-    instrumentation::register_metric_schema, logging::build_subscriber_with_tracer,
-    otlp::build_tracer_provider, prometheus::install_prometheus_recorder,
+    RedactionLimitsError, SentryConfig, SentryConfigError,
+    error_reporting::init_sentry,
+    instrumentation::register_metric_schema,
+    logging::build_subscriber_with_tracer,
+    otlp::{build_local_tracer_provider, build_tracer_provider},
+    prometheus::install_prometheus_recorder,
    propagation::install_trace_context_propagator,
 };

 #[must_use = "observability resources must be retained until process shutdown"]
 pub struct ObservabilityLifecycle {
    metrics_handle: metrics_exporter_prometheus::PrometheusHandle,
-    tracer_provider: Option<opentelemetry_sdk::trace::SdkTracerProvider>,
+    _tracer_provider: opentelemetry_sdk::trace::SdkTracerProvider,
+    trace_export_enabled: bool,
    sentry_guard: Option<sentry::ClientInitGuard>,
 }

 impl ObservabilityLifecycle {
    pub fn init(config: ObservabilityConfig) -> Result<Self, ObservabilityInitError> {
+        Self::init_with_exporters(
+            config,
+            SentryConfig::parse(None)?,
+            OtlpTraceConfig::default(),
+        )
+    }
+
+    pub fn init_with_exporters(
+        config: ObservabilityConfig,
+        sentry_config: SentryConfig,
+        trace_config: OtlpTraceConfig,
+    ) -> Result<Self, ObservabilityInitError> {
        let identity = config.identity().clone();
        let redaction_limits = config.redaction_limits();
-        let sentry_config = SentryConfig::from_env()?;
-        let trace_config = OtlpTraceConfig::from_env()?;
-        let tracing = build_tracer_provider(&identity, &trace_config)?;
-        let tracer = tracing.as_ref().map(|(_, tracer)| tracer.clone());
+        let exported_tracing = build_tracer_provider(&identity, &trace_config)?;
+        let trace_export_enabled = exported_tracing.is_some();
+        let (tracer_provider, tracer) =
+            exported_tracing.unwrap_or_else(|| build_local_tracer_provider(&identity));
        install_trace_context_propagator();
-        build_subscriber_with_tracer(config, io::stdout, tracer)?
+        build_subscriber_with_tracer(config, io::stdout, Some(tracer))?
            .try_init()
            .map_err(|_| ObservabilityInitError::SubscriberAlreadyInitialized)?;
        let metrics_handle = install_prometheus_recorder(&identity)?;
@@ -37,7 +53,8 @@ impl ObservabilityLifecycle {

        Ok(Self {
            metrics_handle,
-            tracer_provider: tracing.map(|(provider, _)| provider),
+            _tracer_provider: tracer_provider,
+            trace_export_enabled,
            sentry_guard,
        })
    }
@@ -47,7 +64,7 @@ impl ObservabilityLifecycle {
    }

    pub fn traces_enabled(&self) -> bool {
-        self.tracer_provider.is_some()
+        self.trace_export_enabled
    }

    pub fn critical_errors_enabled(&self) -> bool {
@@ -77,6 +94,8 @@ pub enum ObservabilityInitError {
    InvalidRedactionLimits(#[from] RedactionLimitsError),
    #[error("invalid log filter")]
    InvalidFilter,
+    #[error("log event budget cannot hold canonical correlation fields")]
+    LogEventBudgetTooSmall,
    #[error("global tracing subscriber is already initialized")]
    SubscriberAlreadyInitialized,
    #[error(transparent)]
@@ -13,6 +13,7 @@ use tracing_subscriber::{

 use crate::{
    ObservabilityConfig, ObservabilityInitError, RedactionLimits, ServiceIdentity,
+    current_request_correlation,
    propagation::current_trace_id,
    redaction::{redact_value, truncate_string},
    schema::LogEnvelope,
@@ -38,6 +39,9 @@ where
 {
    let (identity, filter, limits) = config.into_parts();
    limits.validate()?;
+    if required_correlated_log_budget(&identity) > limits.max_event_bytes {
+        return Err(ObservabilityInitError::LogEventBudgetTooSmall);
+    }
    let filter = EnvFilter::try_new(filter).map_err(|_| ObservabilityInitError::InvalidFilter)?;
    let formatter = JsonEventFormatter::new(identity, limits);
    let fmt_layer = tracing_subscriber::fmt::layer()
@@ -58,6 +62,22 @@ where
        .with(otel_layer))
 }

+fn required_correlated_log_budget(identity: &ServiceIdentity) -> usize {
+    let envelope = LogEnvelope {
+        timestamp: "9999-12-31T23:59:59.999999999Z".to_owned(),
+        level: "ERROR".to_owned(),
+        service: identity.service().to_owned(),
+        version: identity.version().to_owned(),
+        environment: identity.environment().to_owned(),
+        target: "0123456789abcdef".to_owned(),
+        event: "0123456789abcdef".to_owned(),
+        request_id: Some("r".repeat(128)),
+        trace_id: Some("a".repeat(32)),
+        fields: Map::from_iter([("truncated".to_owned(), Value::Bool(true))]),
+    };
+    serde_json::to_vec(&envelope).map_or(usize::MAX, |value| value.len().saturating_add(1))
+}
+
 #[derive(Clone, Debug)]
 struct JsonEventFormatter {
    identity: ServiceIdentity,
@@ -75,10 +95,10 @@ impl JsonEventFormatter {
        event.record(&mut visitor);
        let mut raw_fields = visitor.fields;
        let request_id = take_correlation_id(&mut raw_fields, "request_id")
-            .map(|value| truncate_string(&value, self.limits.max_string_bytes));
+            .or_else(|| current_request_correlation().0);
        let trace_id = take_correlation_id(&mut raw_fields, "trace_id")
-            .or_else(current_trace_id)
-            .map(|value| truncate_string(&value, self.limits.max_string_bytes));
+            .or_else(|| current_request_correlation().1)
+            .or_else(current_trace_id);
        let cleaned = redact_value(&Value::Object(raw_fields), self.limits);
        let fields = cleaned.as_object().cloned().unwrap_or_default();
        let timestamp = OffsetDateTime::now_utc()
@@ -110,19 +130,11 @@ impl JsonEventFormatter {
        let fallback_string_limit = self.limits.max_string_bytes.min(64);
        envelope.target = truncate_string(&envelope.target, fallback_string_limit);
        envelope.event = truncate_string(&envelope.event, fallback_string_limit);
-        envelope.request_id = envelope
-            .request_id
-            .map(|value| truncate_string(&value, fallback_string_limit));
-        envelope.trace_id = envelope
-            .trace_id
-            .map(|value| truncate_string(&value, fallback_string_limit));
        let serialized = serde_json::to_string(&envelope).map_err(|_| fmt::Error)?;
        if serialized.len() <= line_budget {
            return Ok(serialized);
        }

-        envelope.request_id = None;
-        envelope.trace_id = None;
        envelope.target = truncate_string(&envelope.target, 16);
        envelope.event = truncate_string(&envelope.event, 16);
        let serialized = serde_json::to_string(&envelope).map_err(|_| fmt::Error)?;
@@ -202,14 +214,27 @@ impl Visit for JsonFieldVisitor {
 }

 fn take_correlation_id(fields: &mut Map<String, Value>, name: &str) -> Option<String> {
-    let value = fields.remove(name)?;
-    let value = match value {
-        Value::String(value) => value,
-        Value::Number(value) => value.to_string(),
-        Value::Bool(value) => value.to_string(),
-        Value::Null | Value::Array(_) | Value::Object(_) => return None,
+    let Value::String(value) = fields.remove(name)? else {
+        return None;
    };
-    (!value.is_empty()).then_some(value)
+    let valid = match name {
+        "trace_id" => {
+            value.len() == 32
+                && value != "00000000000000000000000000000000"
+                && value
+                    .bytes()
+                    .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte))
+        }
+        "request_id" | "correlation_id" => {
+            !value.is_empty()
+                && value.len() <= 128
+                && value
+                    .bytes()
+                    .all(|byte| byte.is_ascii_graphic() && byte != b',' && byte != b';')
+        }
+        _ => false,
+    };
+    valid.then_some(value)
 }

 fn is_correlation_field(name: &str) -> bool {
@@ -1,4 +1,4 @@
-use std::{collections::HashMap, env, fmt, time::Duration};
+use std::{collections::HashMap, fmt, time::Duration};

 use axum::http::{HeaderName, HeaderValue};
 use opentelemetry::{
@@ -118,8 +118,36 @@ impl fmt::Debug for OtlpTraceConfig {
 }

 impl OtlpTraceConfig {
-    pub fn from_env() -> Result<Self, OtlpTraceConfigError> {
-        OtlpEnvSettings::from_env()?.into_config()
+    #[allow(clippy::too_many_arguments)]
+    pub fn from_values(
+        generic_endpoint: Option<String>,
+        traces_endpoint: Option<String>,
+        generic_protocol: Option<String>,
+        traces_protocol: Option<String>,
+        generic_timeout: Option<String>,
+        traces_timeout: Option<String>,
+        generic_headers: Option<String>,
+        traces_headers: Option<String>,
+        max_queue_size: usize,
+        max_export_batch_size: usize,
+        scheduled_delay: String,
+        batch_export_timeout: String,
+    ) -> Result<Self, OtlpTraceConfigError> {
+        OtlpEnvSettings {
+            traces_endpoint,
+            generic_endpoint,
+            traces_protocol,
+            generic_protocol,
+            traces_timeout,
+            generic_timeout,
+            traces_headers,
+            generic_headers,
+            max_queue_size: Some(max_queue_size.to_string()),
+            max_export_batch_size: Some(max_export_batch_size.to_string()),
+            scheduled_delay: Some(scheduled_delay),
+            batch_export_timeout: Some(batch_export_timeout),
+        }
+        .into_config()
    }

    fn from_settings(settings: OtlpEnvSettings) -> Result<Self, OtlpTraceConfigError> {
@@ -232,6 +260,17 @@ impl OtlpTraceConfig {
    }
 }

+impl Default for OtlpTraceConfig {
+    fn default() -> Self {
+        Self {
+            endpoint: None,
+            export_timeout: DEFAULT_EXPORT_TIMEOUT,
+            batch: OtlpBatchConfig::default(),
+            headers: HashMap::new(),
+        }
+    }
+}
+
 #[derive(Default)]
 struct OtlpEnvSettings {
    traces_endpoint: Option<String>,
@@ -249,23 +288,6 @@ struct OtlpEnvSettings {
 }

 impl OtlpEnvSettings {
-    fn from_env() -> Result<Self, OtlpTraceConfigError> {
-        Ok(Self {
-            traces_endpoint: optional_env("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT")?,
-            generic_endpoint: optional_env("OTEL_EXPORTER_OTLP_ENDPOINT")?,
-            traces_protocol: optional_env("OTEL_EXPORTER_OTLP_TRACES_PROTOCOL")?,
-            generic_protocol: optional_env("OTEL_EXPORTER_OTLP_PROTOCOL")?,
-            traces_timeout: optional_env("OTEL_EXPORTER_OTLP_TRACES_TIMEOUT")?,
-            generic_timeout: optional_env("OTEL_EXPORTER_OTLP_TIMEOUT")?,
-            traces_headers: optional_env("OTEL_EXPORTER_OTLP_TRACES_HEADERS")?,
-            generic_headers: optional_env("OTEL_EXPORTER_OTLP_HEADERS")?,
-            max_queue_size: optional_env("OTEL_BSP_MAX_QUEUE_SIZE")?,
-            max_export_batch_size: optional_env("OTEL_BSP_MAX_EXPORT_BATCH_SIZE")?,
-            scheduled_delay: optional_env("OTEL_BSP_SCHEDULE_DELAY")?,
-            batch_export_timeout: optional_env("OTEL_BSP_EXPORT_TIMEOUT")?,
-        })
-    }
-
    fn into_config(self) -> Result<OtlpTraceConfig, OtlpTraceConfigError> {
        OtlpTraceConfig::from_settings(self)
    }
@@ -313,7 +335,28 @@ pub fn build_tracer_provider(
    let processor = BatchSpanProcessor::builder(ObservedSpanExporter(exporter))
        .with_batch_config(config.batch.sdk_config())
        .build();
-    let resource = Resource::builder_empty()
+    let resource = trace_resource(identity);
+    let provider = SdkTracerProvider::builder()
+        .with_span_processor(processor)
+        .with_resource(resource)
+        .build();
+    let tracer = provider.tracer("crank");
+
+    Ok(Some((provider, tracer)))
+}
+
+pub(crate) fn build_local_tracer_provider(
+    identity: &ServiceIdentity,
+) -> (SdkTracerProvider, SdkTracer) {
+    let provider = SdkTracerProvider::builder()
+        .with_resource(trace_resource(identity))
+        .build();
+    let tracer = provider.tracer("crank");
+    (provider, tracer)
+}
+
+fn trace_resource(identity: &ServiceIdentity) -> Resource {
+    Resource::builder_empty()
        .with_attributes([
            KeyValue::new("service.name", identity.service().to_owned()),
            KeyValue::new("service.version", identity.version().to_owned()),
@@ -322,14 +365,7 @@ pub fn build_tracer_provider(
                identity.environment().to_owned(),
            ),
        ])
-        .build();
-    let provider = SdkTracerProvider::builder()
-        .with_span_processor(processor)
-        .with_resource(resource)
-        .build();
-    let tracer = provider.tracer("crank");
-
-    Ok(Some((provider, tracer)))
+        .build()
 }

 #[derive(Debug)]
@@ -405,7 +441,7 @@ fn is_allowed_span_attribute(attribute: &KeyValue) -> bool {
    };
    let value = value.as_str();
    match attribute.key.as_str() {
-        "request_id" => crate::RequestId::is_valid(value),
+        "request_id" => is_valid_request_id(value),
        "stage" => is_allowed_span_name(value),
        "outcome" => matches!(
            value,
@@ -453,6 +489,14 @@ fn is_allowed_span_attribute(attribute: &KeyValue) -> bool {
    }
 }

+fn is_valid_request_id(value: &str) -> bool {
+    !value.is_empty()
+        && value.len() <= 128
+        && value
+            .bytes()
+            .all(|byte| byte.is_ascii_graphic() && byte != b',' && byte != b';')
+}
+
 #[derive(Clone, Copy)]
 enum EndpointKind {
    Trace,
@@ -514,17 +558,6 @@ fn parse_headers(value: &str) -> Result<HashMap<String, String>, OtlpTraceConfig
        })
 }

-fn optional_env(field: &'static str) -> Result<Option<String>, OtlpTraceConfigError> {
-    match env::var(field) {
-        Ok(value) if value.is_empty() => Ok(None),
-        Ok(value) => Ok(Some(value)),
-        Err(env::VarError::NotPresent) => Ok(None),
-        Err(env::VarError::NotUnicode(_)) => {
-            Err(OtlpTraceConfigError::InvalidEnvironmentEncoding { field })
-        }
-    }
-}
-
 fn usize_env(
    field: &'static str,
    value: Option<String>,
@@ -586,7 +619,10 @@ mod tests {
    use tracing::{Instrument, info_span};
    use tracing_subscriber::layer::SubscriberExt;

-    use super::{OtlpBatchConfig, OtlpEnvSettings, OtlpTraceConfig, build_tracer_provider};
+    use super::{
+        OtlpBatchConfig, OtlpEnvSettings, OtlpTraceConfig, build_local_tracer_provider,
+        build_tracer_provider,
+    };
    use crate::ServiceIdentity;

    #[test]
@@ -708,6 +744,15 @@ mod tests {
        assert!(build_tracer_provider(&identity, &config).unwrap().is_none());
    }

+    #[test]
+    fn local_provider_creates_valid_context_without_an_exporter() {
+        let identity = ServiceIdentity::try_new("admin-api", "0.3.1", "test").unwrap();
+        let (provider, tracer) = build_local_tracer_provider(&identity);
+        let span = tracer.start("http.request");
+        assert!(span.span_context().is_valid());
+        provider.shutdown().unwrap();
+    }
+
    #[test]
    fn real_http_protobuf_export_contains_resource_and_trace() {
        let listener = TcpListener::bind("127.0.0.1:0").unwrap();
@@ -1,4 +1,4 @@
-use std::{env, net::SocketAddr};
+use std::net::SocketAddr;

 use axum::{
    Router,
@@ -19,8 +19,6 @@ use tokio::net::TcpListener;

 use crate::{DURATION_BUCKETS_SECONDS, ServiceIdentity};

-const METRICS_ENABLED_ENV: &str = "CRANK_METRICS_ENABLED";
-const METRICS_TOKEN_ENV: &str = "CRANK_METRICS_BEARER_TOKEN";
 const PROMETHEUS_CONTENT_TYPE: &str = "text/plain; version=0.0.4; charset=utf-8";

 #[derive(Clone)]
@@ -62,33 +60,6 @@ impl MetricsConfig {
        })
    }

-    pub fn from_env(
-        bind_env: &'static str,
-        default_bind: SocketAddr,
-    ) -> Result<Self, MetricsConfigError> {
-        let enabled = parse_enabled(env::var(METRICS_ENABLED_ENV))?;
-        let bind_addr = match env::var(bind_env) {
-            Ok(raw) => raw
-                .parse()
-                .map_err(|_| MetricsConfigError::InvalidBindAddress { field: bind_env })?,
-            Err(env::VarError::NotPresent) => default_bind,
-            Err(env::VarError::NotUnicode(_)) => {
-                return Err(MetricsConfigError::InvalidEnvironmentEncoding { field: bind_env });
-            }
-        };
-        let bearer_token = match env::var(METRICS_TOKEN_ENV) {
-            Ok(token) => Some(token),
-            Err(env::VarError::NotPresent) => None,
-            Err(env::VarError::NotUnicode(_)) => {
-                return Err(MetricsConfigError::InvalidEnvironmentEncoding {
-                    field: METRICS_TOKEN_ENV,
-                });
-            }
-        };
-
-        Self::new(enabled, bind_addr, bearer_token)
-    }
-
    pub fn enabled(&self) -> bool {
        self.enabled
    }
@@ -280,17 +251,3 @@ fn bearer_token(headers: &HeaderMap) -> Option<&[u8]> {
 fn token_digest(token: &[u8]) -> [u8; 32] {
    Sha256::digest(token).into()
 }
-
-fn parse_enabled(value: Result<String, env::VarError>) -> Result<bool, MetricsConfigError> {
-    match value {
-        Ok(raw) => match raw.to_ascii_lowercase().as_str() {
-            "true" | "1" => Ok(true),
-            "false" | "0" => Ok(false),
-            _ => Err(MetricsConfigError::InvalidEnabledFlag),
-        },
-        Err(env::VarError::NotPresent) => Ok(true),
-        Err(env::VarError::NotUnicode(_)) => Err(MetricsConfigError::InvalidEnvironmentEncoding {
-            field: METRICS_ENABLED_ENV,
-        }),
-    }
-}
@@ -1,74 +0,0 @@
-use axum::http::{HeaderMap, HeaderValue};
-use crank_observability::RequestId;
-use uuid::Version;
-
-#[test]
-fn preserves_valid_opaque_request_id() {
-    let request_id = RequestId::resolve(Some("req_test-123/abc"));
-
-    assert_eq!(request_id.as_str(), "req_test-123/abc");
-}
-
-#[test]
-fn replaces_missing_and_invalid_values_with_uuid_v7() {
-    for candidate in [
-        None,
-        Some(""),
-        Some("bad value"),
-        Some(" leading"),
-        Some("trailing "),
-        Some("bad,value"),
-        Some("bad;value"),
-        Some("я"),
-    ] {
-        let request_id = RequestId::resolve(candidate);
-        let parsed = uuid::Uuid::parse_str(request_id.as_str()).expect("generated UUID");
-
-        assert_eq!(parsed.get_version(), Some(Version::SortRand));
-    }
-}
-
-#[test]
-fn rejects_values_over_the_shared_limit() {
-    let oversized = "x".repeat(RequestId::MAX_LEN + 1);
-    let request_id = RequestId::resolve(Some(&oversized));
-
-    assert_ne!(request_id.as_str(), oversized);
-    assert_eq!(
-        uuid::Uuid::parse_str(request_id.as_str())
-            .expect("generated UUID")
-            .get_version(),
-        Some(Version::SortRand)
-    );
-}
-
-#[test]
-fn resolves_exactly_one_header_value_and_rejects_ambiguous_values() {
-    let mut single = HeaderMap::new();
-    single.insert(
-        "x-request-id",
-        HeaderValue::from_static("opaque-request-id"),
-    );
-
-    assert_eq!(
-        RequestId::resolve_from_headers(&single).as_str(),
-        "opaque-request-id"
-    );
-
-    let mut ambiguous = HeaderMap::new();
-    ambiguous.append("x-request-id", HeaderValue::from_static("first-request-id"));
-    ambiguous.append(
-        "x-request-id",
-        HeaderValue::from_static("second-request-id"),
-    );
-
-    let generated = RequestId::resolve_from_headers(&ambiguous);
-    assert_ne!(generated.as_str(), "first-request-id");
-    assert_ne!(generated.as_str(), "second-request-id");
-    assert_eq!(
-        uuid::Uuid::parse_str(generated.as_str())
-            .expect("generated UUID")
-            .get_version(),
-        Some(Version::SortRand)
-    );
-}
@@ -132,11 +132,11 @@ fn correlation_fields_are_distinct_and_only_present_when_recorded() {
        tracing::info!(
            name: "admin.request.completed",
            request_id = "req-123",
-            trace_id = "trace-456"
+            trace_id = "0af7651916cd43dd8448eb211c80319c"
        );
    });
    assert_eq!(present[0]["request_id"], "req-123");
-    assert_eq!(present[0]["trace_id"], "trace-456");
+    assert_eq!(present[0]["trace_id"], "0af7651916cd43dd8448eb211c80319c");
    assert!(present[0]["fields"].get("request_id").is_none());
    assert!(present[0]["fields"].get("trace_id").is_none());

@@ -148,7 +148,7 @@ fn correlation_fields_are_distinct_and_only_present_when_recorded() {
 }

 #[test]
-fn correlation_fields_preserve_scalar_display_values_before_field_limits() {
+fn correlation_fields_accept_valid_strings_and_reject_non_string_values() {
    let limits = RedactionLimits {
        max_object_fields: 1,
        ..RedactionLimits::default()
@@ -164,7 +164,7 @@ fn correlation_fields_preserve_scalar_display_values_before_field_limits() {
    });

    assert_eq!(events[0]["request_id"], "123");
-    assert_eq!(events[0]["trace_id"], "true");
+    assert!(events[0].get("trace_id").is_none());
 }

 #[test]
@@ -321,7 +321,7 @@ fn subscriber_rejects_limits_that_cannot_hold_an_event() {
 }

 #[test]
-fn minimum_event_budget_handles_maximum_identity_labels() {
+fn event_budget_rejects_maximum_identity_labels_when_correlation_cannot_fit() {
    let writer = SharedWriter::default();
    let config = ObservabilityConfig::new(
        ServiceIdentity::try_new("s".repeat(64), "v".repeat(64), "e".repeat(64))
@@ -332,20 +332,7 @@ fn minimum_event_budget_handles_maximum_identity_labels() {
            ..RedactionLimits::default()
        },
    );
-    let subscriber =
-        build_subscriber(config, writer.clone()).expect("minimum valid budget must be usable");
-
-    tracing::subscriber::with_default(subscriber, || {
-        tracing::info!(
-            name: "event-name-that-is-intentionally-longer-than-the-fallback-limit",
-            description = %"x".repeat(4096),
-        );
-    });
-
-    let output = writer.output();
-    assert!(output.len() <= 512);
-    assert_eq!(output.lines().count(), 1);
-    serde_json::from_str::<Value>(output.trim_end()).expect("bounded line must remain valid JSON");
+    assert!(build_subscriber(config, writer).is_err());
 }

 #[test]
@@ -97,6 +97,8 @@ fn schema_is_closed_and_uses_fixed_duration_buckets() {
            "agent_id",
            "operation_id",
            "request_id",
+            "trace_id",
+            "correlation_id",
            "url",
            "error_message",
            "text",
@@ -0,0 +1,60 @@
+use std::sync::Arc;
+
+use crank_observability::{current_request_correlation, with_request_correlation};
+
+#[tokio::test]
+async fn concurrent_request_correlation_is_task_local() {
+    let barrier = Arc::new(tokio::sync::Barrier::new(2));
+    let first = observe(
+        "request-first",
+        "0af7651916cd43dd8448eb211c80319c",
+        Arc::clone(&barrier),
+    );
+    let second = observe(
+        "request-second",
+        "1af7651916cd43dd8448eb211c80319c",
+        barrier,
+    );
+    let (first, second) = tokio::join!(first, second);
+
+    assert_eq!(
+        first,
+        (
+            Some("request-first".to_owned()),
+            Some("0af7651916cd43dd8448eb211c80319c".to_owned()),
+        )
+    );
+    assert_eq!(
+        second,
+        (
+            Some("request-second".to_owned()),
+            Some("1af7651916cd43dd8448eb211c80319c".to_owned()),
+        )
+    );
+    assert_eq!(current_request_correlation(), (None, None));
+}
+
+#[tokio::test]
+async fn invalid_correlation_strings_never_enter_task_local_state() {
+    let observed = with_request_correlation(
+        "bad request id".to_owned(),
+        "CANARY-NOT-A-TRACE-ID".to_owned(),
+        async { current_request_correlation() },
+    )
+    .await;
+
+    assert_eq!(observed, (None, None));
+}
+
+async fn observe(
+    request_id: &str,
+    trace_id: &str,
+    barrier: Arc<tokio::sync::Barrier>,
+) -> (Option<String>, Option<String>) {
+    with_request_correlation(request_id.to_owned(), trace_id.to_owned(), async move {
+        barrier.wait().await;
+        tokio::task::yield_now().await;
+        current_request_correlation()
+    })
+    .await
+}
@@ -2,6 +2,8 @@ use thiserror::Error;

 #[derive(Debug, Error)]
 pub enum RegistryError {
+    #[error(transparent)]
+    Migration(#[from] crate::migrations::MigrationError),
    #[error(transparent)]
    Storage(#[from] sqlx::Error),
    #[error(transparent)]
@@ -80,4 +82,6 @@ pub enum RegistryError {
    InvalidEnumRepresentation { field: &'static str },
    #[error("invalid numeric value for field {field}: {value}")]
    InvalidNumericValue { field: &'static str, value: i64 },
+    #[error("invalid correlation identity for field {field}")]
+    InvalidCorrelationIdentity { field: &'static str },
 }
@@ -1,77 +1,14 @@
-use std::sync::Arc;
-
-use sqlx::{PgPool, query};
-
-use crate::RegistryError;
-
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub struct ExtensionMigration {
    pub version: u32,
-    pub sql: &'static str,
+    pub checksum: &'static str,
+    pub source_digest: &'static str,
+    pub phase: &'static str,
+    pub compatibility: &'static str,
+    pub owner: &'static str,
 }

 pub trait RegistryExtension: Send + Sync {
    fn name(&self) -> &str;
    fn migrations(&self) -> &[ExtensionMigration];
 }
-
-pub async fn apply_extension_migrations(
-    pool: &PgPool,
-    extensions: &[Arc<dyn RegistryExtension>],
-) -> Result<(), RegistryError> {
-    query(
-        "create table if not exists __crank_ext_migrations (
-            extension_name text not null,
-            version integer not null,
-            applied_at timestamptz not null default now(),
-            primary key (extension_name, version)
-        )",
-    )
-    .execute(pool)
-    .await?;
-
-    for extension in extensions {
-        for migration in extension.migrations() {
-            let already_applied = query(
-                "select 1
-                 from __crank_ext_migrations
-                 where extension_name = $1 and version = $2",
-            )
-            .bind(extension.name())
-            .bind(i32::try_from(migration.version).map_err(|_| {
-                RegistryError::InvalidNumericValue {
-                    field: "extension_migration.version",
-                    value: migration.version as i64,
-                }
-            })?)
-            .fetch_optional(pool)
-            .await?
-            .is_some();
-
-            if already_applied {
-                continue;
-            }
-
-            let mut tx = pool.begin().await?;
-
-            query(migration.sql).execute(&mut *tx).await?;
-            query(
-                "insert into __crank_ext_migrations (extension_name, version)
-                 values ($1, $2)",
-            )
-            .bind(extension.name())
-            .bind(i32::try_from(migration.version).map_err(|_| {
-                RegistryError::InvalidNumericValue {
-                    field: "extension_migration.version",
-                    value: migration.version as i64,
-                }
-            })?)
-            .execute(&mut *tx)
-            .await?;
-
-            tx.commit().await?;
-        }
-    }
-
-    Ok(())
-}
@@ -5,7 +5,11 @@ mod model;
 mod postgres;

 pub use error::RegistryError;
-pub use ext::{ExtensionMigration, RegistryExtension, apply_extension_migrations};
+pub use ext::{ExtensionMigration, RegistryExtension};
+pub use migrations::{
+    BackfillBatch, BackfillPolicy, MigrationApplyResult, MigrationAuthority, MigrationDescriptor,
+    MigrationError, MigrationPreflight,
+};

 pub mod records {
    pub use crate::model::{
@@ -39,8 +43,12 @@ pub mod requests {
 }

 pub mod infrastructure {
-    pub use crate::ext::{ExtensionMigration, RegistryExtension, apply_extension_migrations};
+    pub use crate::ext::{ExtensionMigration, RegistryExtension};
    pub use crate::postgres::{PostgresPoolConfig, PostgresPoolConfigError, PostgresRegistry};
+    pub use crate::{
+        BackfillBatch, BackfillPolicy, MigrationApplyResult, MigrationAuthority,
+        MigrationDescriptor, MigrationError, MigrationPreflight,
+    };
 }

 pub use model::{
@@ -1,721 +1,10 @@
-use sqlx::{PgPool, Postgres, Row, Transaction, query};
+mod authority;
+mod baseline_v1;
+mod schema_guard;

-const CORE_MIGRATION_LOCK_ID: i64 = 0x43_52_41_4E_4B;
-const BASELINE_VERSION: i32 = 1;
-const BASELINE_CHECKSUM: &str = "crank-community-baseline-v1";
+pub use authority::{
+    BackfillBatch, BackfillPolicy, MigrationApplyResult, MigrationAuthority, MigrationDescriptor,
+    MigrationError, MigrationPreflight,
+};

-pub async fn apply_postgres(pool: &PgPool) -> Result<(), sqlx::Error> {
-    let mut transaction = pool.begin().await?;
-    query("select pg_advisory_xact_lock($1)")
-        .bind(CORE_MIGRATION_LOCK_ID)
-        .execute(&mut *transaction)
-        .await?;
-    query(
-        "create table if not exists __crank_core_migrations (
-            version integer primary key,
-            description text not null,
-            checksum text not null,
-            applied_at timestamptz not null default now()
-        )",
-    )
-    .execute(&mut *transaction)
-    .await?;
-
-    let applied = query(
-        "select version, checksum
-         from __crank_core_migrations
-         order by version",
-    )
-    .fetch_all(&mut *transaction)
-    .await?;
-    for row in &applied {
-        let version = row.try_get::<i32, _>("version")?;
-        let checksum = row.try_get::<String, _>("checksum")?;
-        if version != BASELINE_VERSION || checksum != BASELINE_CHECKSUM {
-            return Err(sqlx::Error::Protocol(format!(
-                "unsupported or modified core migration: version={version}, checksum={checksum}"
-            )));
-        }
-    }
-
-    if applied.is_empty() {
-        apply_baseline(&mut transaction).await?;
-        query(
-            "insert into __crank_core_migrations (version, description, checksum)
-             values ($1, $2, $3)",
-        )
-        .bind(BASELINE_VERSION)
-        .bind("community baseline")
-        .bind(BASELINE_CHECKSUM)
-        .execute(&mut *transaction)
-        .await?;
-    }
-
-    transaction.commit().await?;
-    Ok(())
-}
-
-async fn apply_baseline(transaction: &mut Transaction<'_, Postgres>) -> Result<(), sqlx::Error> {
-    query(
-        "create table if not exists workspaces (
-            id text primary key,
-            slug text not null unique,
-            display_name text not null,
-            status text not null,
-            settings_json jsonb not null default '{}'::jsonb,
-            created_at timestamptz not null,
-            updated_at timestamptz not null
-        )",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create table if not exists users (
-            id text primary key,
-            email text not null unique,
-            display_name text not null,
-            password_hash text null,
-            status text not null,
-            created_at timestamptz not null
-        )",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query("alter table users add column if not exists password_hash text null")
-        .execute(&mut **transaction)
-        .await?;
-
-    query(
-        "insert into users (
-            id,
-            email,
-            display_name,
-            status,
-            created_at
-        ) values (
-            'user_default_owner',
-            'owner@crank.local',
-            'Workspace Owner',
-            'active',
-            now()
-        )
-        on conflict (id) do nothing",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create table if not exists memberships (
-            workspace_id text not null references workspaces(id) on delete cascade,
-            user_id text not null references users(id) on delete cascade,
-            role text not null,
-            created_at timestamptz not null,
-            primary key (workspace_id, user_id)
-        )",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create table if not exists user_sessions (
-            id text primary key,
-            user_id text not null references users(id) on delete cascade,
-            current_workspace_id text null references workspaces(id) on delete set null,
-            secret_hash text not null,
-            status text not null,
-            expires_at timestamptz not null,
-            last_seen_at timestamptz null,
-            created_at timestamptz not null
-        )",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "alter table user_sessions
-         add column if not exists current_workspace_id text null references workspaces(id) on delete set null",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "insert into workspaces (
-            id,
-            slug,
-            display_name,
-            status,
-            settings_json,
-            created_at,
-            updated_at
-        ) values (
-            'ws_default',
-            'default',
-            'Default Workspace',
-            'active',
-            '{}'::jsonb,
-            now(),
-            now()
-        )
-        on conflict (id) do nothing",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "insert into memberships (
-            workspace_id,
-            user_id,
-            role,
-            created_at
-        ) values (
-            'ws_default',
-            'user_default_owner',
-            'owner',
-            now()
-        )
-        on conflict (workspace_id, user_id) do nothing",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create table if not exists invitation_tokens (
-            id text primary key,
-            workspace_id text not null references workspaces(id) on delete cascade,
-            email text not null,
-            role text not null,
-            status text not null,
-            token_hash text not null,
-            expires_at timestamptz not null,
-            created_at timestamptz not null
-        )",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create table if not exists platform_api_keys (
-            id text primary key,
-            workspace_id text not null references workspaces(id) on delete cascade,
-            agent_id text null,
-            name text not null,
-            prefix text not null,
-            secret_hash text not null,
-            key_kind text not null default 'mcp_client',
-            scopes_json jsonb not null,
-            status text not null,
-            created_at timestamptz not null,
-            last_used_at timestamptz null,
-            revoked_at timestamptz null,
-            expires_at timestamptz null,
-            allowed_origins_json jsonb not null default '[]'::jsonb
-        )",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create unique index if not exists platform_api_keys_workspace_name_idx on platform_api_keys(workspace_id, name)",
-    )
-    .execute(&mut **transaction)
-    .await?;
-    query("alter table platform_api_keys add column if not exists agent_id text null")
-        .execute(&mut **transaction)
-        .await?;
-    query(
-        "alter table platform_api_keys add column if not exists key_kind text not null default 'mcp_client'",
-    )
-    .execute(&mut **transaction)
-    .await?;
-    query("alter table platform_api_keys add column if not exists expires_at timestamptz null")
-        .execute(&mut **transaction)
-        .await?;
-    query(
-        "alter table platform_api_keys add column if not exists allowed_origins_json jsonb not null default '[]'::jsonb",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "insert into workspaces (
-            id,
-            slug,
-            display_name,
-            status,
-            settings_json,
-            created_at,
-            updated_at
-        ) values (
-            'ws_default',
-            'default',
-            'Default Workspace',
-            'active',
-            '{}'::jsonb,
-            now(),
-            now()
-        )
-        on conflict (id) do nothing",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create table if not exists operations (
-            id text primary key,
-            workspace_id text null references workspaces(id) on delete cascade,
-            name text not null,
-            display_name text not null,
-            category text not null default 'general',
-            protocol text not null,
-            security_level text not null default 'standard',
-            status text not null,
-            current_draft_version integer not null default 1,
-            latest_published_version integer null,
-            created_at timestamptz not null,
-            updated_at timestamptz not null,
-            published_at timestamptz null
-        )",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query("alter table operations add column if not exists workspace_id text null references workspaces(id) on delete cascade")
-        .execute(&mut **transaction)
-        .await?;
-    query(
-        "alter table operations add column if not exists category text not null default 'general'",
-    )
-    .execute(&mut **transaction)
-    .await?;
-    query(
-        "alter table operations add column if not exists security_level text not null default 'standard'",
-    )
-    .execute(&mut **transaction)
-    .await?;
-    query("update operations set workspace_id = 'ws_default' where workspace_id is null")
-        .execute(&mut **transaction)
-        .await?;
-    query("alter table operations alter column workspace_id set not null")
-        .execute(&mut **transaction)
-        .await?;
-    query("alter table operations drop constraint if exists operations_name_key")
-        .execute(&mut **transaction)
-        .await?;
-    query(
-        "create unique index if not exists operations_workspace_name_idx on operations(workspace_id, name)",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create table if not exists operation_versions (
-            operation_id text not null references operations(id) on delete cascade,
-            version integer not null,
-            status text not null,
-            target_json jsonb not null,
-            input_schema_json jsonb not null,
-            output_schema_json jsonb not null,
-            input_mapping_json jsonb not null,
-            output_mapping_json jsonb not null,
-            execution_config_json jsonb not null,
-            tool_description_json jsonb not null,
-            samples_json jsonb null,
-            generated_draft_json jsonb null,
-            config_export_json jsonb null,
-            wizard_state_json jsonb null,
-            change_note text null,
-            created_at timestamptz not null,
-            created_by text null,
-            primary key (operation_id, version)
-        )",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query("alter table operation_versions add column if not exists wizard_state_json jsonb null")
-        .execute(&mut **transaction)
-        .await?;
-
-    query(
-        "create table if not exists published_operations (
-            operation_id text primary key references operations(id) on delete cascade,
-            version integer not null,
-            published_at timestamptz not null,
-            published_by text null,
-            foreign key (operation_id, version) references operation_versions(operation_id, version) on delete cascade
-        )",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create table if not exists operation_samples (
-            id text primary key,
-            operation_id text not null references operations(id) on delete cascade,
-            version integer not null,
-            sample_kind text not null,
-            storage_ref text not null,
-            content_type text not null,
-            file_name text null,
-            created_at timestamptz not null,
-            foreign key (operation_id, version) references operation_versions(operation_id, version) on delete cascade
-        )",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create table if not exists descriptors (
-            id text primary key,
-            operation_id text null references operations(id) on delete cascade,
-            version integer null,
-            descriptor_kind text not null,
-            storage_ref text not null,
-            source_name text null,
-            package_index_json jsonb null,
-            created_at timestamptz not null,
-            foreign key (operation_id, version) references operation_versions(operation_id, version) on delete cascade
-        )",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create table if not exists auth_profiles (
-            id text primary key,
-            workspace_id text null references workspaces(id) on delete cascade,
-            name text not null,
-            kind text not null,
-            config_json jsonb not null,
-            created_at timestamptz not null,
-            updated_at timestamptz not null
-        )",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query("alter table auth_profiles add column if not exists workspace_id text null references workspaces(id) on delete cascade")
-        .execute(&mut **transaction)
-        .await?;
-    query("update auth_profiles set workspace_id = 'ws_default' where workspace_id is null")
-        .execute(&mut **transaction)
-        .await?;
-    query("alter table auth_profiles alter column workspace_id set not null")
-        .execute(&mut **transaction)
-        .await?;
-    query("alter table auth_profiles drop constraint if exists auth_profiles_name_key")
-        .execute(&mut **transaction)
-        .await?;
-    query(
-        "create unique index if not exists auth_profiles_workspace_name_idx on auth_profiles(workspace_id, name)",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create table if not exists workspace_upstreams (
-            id text primary key,
-            workspace_id text not null references workspaces(id) on delete cascade,
-            name text not null,
-            base_url text not null,
-            static_headers_json jsonb not null default '{}'::jsonb,
-            auth_profile_id text null references auth_profiles(id) on delete set null,
-            created_at timestamptz not null,
-            updated_at timestamptz not null
-        )",
-    )
-    .execute(&mut **transaction)
-    .await?;
-    query(
-        "create unique index if not exists workspace_upstreams_workspace_name_idx on workspace_upstreams(workspace_id, name)",
-    )
-    .execute(&mut **transaction)
-    .await?;
-    query(
-        "create unique index if not exists workspace_upstreams_workspace_base_auth_idx on workspace_upstreams(workspace_id, base_url, coalesce(auth_profile_id, ''))",
-    )
-    .execute(&mut **transaction)
-    .await?;
-    query(
-        "insert into workspace_upstreams (
-            id,
-            workspace_id,
-            name,
-            base_url,
-            static_headers_json,
-            auth_profile_id,
-            created_at,
-            updated_at
-        )
-        select
-            'upstream_frankfurter_' || w.id,
-            w.id,
-            'Frankfurter',
-            'https://api.frankfurter.dev',
-            '{}'::jsonb,
-            null,
-            now(),
-            now()
-        from workspaces w
-        where not exists (
-            select 1
-            from workspace_upstreams wu
-            where wu.workspace_id = w.id
-              and wu.name = 'Frankfurter'
-        )",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create table if not exists secrets (
-            id text primary key,
-            workspace_id text not null references workspaces(id) on delete cascade,
-            name text not null,
-            kind text not null,
-            status text not null,
-            current_version integer not null,
-            last_used_at timestamptz null,
-            created_at timestamptz not null,
-            updated_at timestamptz not null
-        )",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create unique index if not exists secrets_workspace_name_idx on secrets(workspace_id, name)",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create table if not exists secret_versions (
-            secret_id text not null references secrets(id) on delete cascade,
-            version integer not null,
-            ciphertext text not null,
-            key_version text not null,
-            created_at timestamptz not null,
-            created_by text null references users(id) on delete set null,
-            primary key (secret_id, version)
-        )",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create table if not exists yaml_import_jobs (
-            id text primary key,
-            source_sample_id text null references operation_samples(id) on delete set null,
-            status text not null,
-            format_version text not null,
-            mode text not null,
-            result_operation_id text null references operations(id) on delete set null,
-            result_version integer null,
-            error_text text null,
-            created_at timestamptz not null,
-            finished_at timestamptz null
-        )",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create table if not exists import_jobs (
-            id text primary key,
-            workspace_id text not null references workspaces(id) on delete cascade,
-            kind text not null,
-            source_format text not null,
-            source_version text null,
-            status text not null,
-            preview_payload jsonb not null,
-            created_operation_ids jsonb not null default '[]'::jsonb,
-            error_text text null,
-            created_at timestamptz not null,
-            expires_at timestamptz not null,
-            finished_at timestamptz null
-        )",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create table if not exists agents (
-            id text primary key,
-            workspace_id text not null references workspaces(id) on delete cascade,
-            slug text not null,
-            display_name text not null,
-            description text not null,
-            status text not null,
-            current_draft_version integer not null default 1,
-            latest_published_version integer null,
-            created_at timestamptz not null,
-            updated_at timestamptz not null,
-            published_at timestamptz null
-        )",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create unique index if not exists agents_workspace_slug_idx on agents(workspace_id, slug)",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create table if not exists agent_versions (
-            agent_id text not null references agents(id) on delete cascade,
-            version integer not null,
-            status text not null,
-            instructions_json jsonb not null,
-            tool_selection_policy_json jsonb not null,
-            created_at timestamptz not null,
-            primary key (agent_id, version)
-        )",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create table if not exists agent_operation_bindings (
-            agent_id text not null references agents(id) on delete cascade,
-            agent_version integer not null,
-            operation_id text not null references operations(id) on delete cascade,
-            operation_version integer not null,
-            tool_name text not null,
-            tool_title text not null,
-            tool_description_override text null,
-            enabled boolean not null default true,
-            foreign key (agent_id, agent_version) references agent_versions(agent_id, version) on delete cascade,
-            foreign key (operation_id, operation_version) references operation_versions(operation_id, version) on delete cascade
-        )",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create unique index if not exists agent_bindings_tool_name_idx on agent_operation_bindings(agent_id, agent_version, tool_name)",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create table if not exists published_agents (
-            agent_id text primary key references agents(id) on delete cascade,
-            version integer not null,
-            published_at timestamptz not null,
-            published_by text null,
-            foreign key (agent_id, version) references agent_versions(agent_id, version) on delete cascade
-        )",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create table if not exists approval_requests (
-            id text primary key,
-            workspace_id text not null references workspaces(id) on delete cascade,
-            agent_id text not null references agents(id) on delete cascade,
-            operation_id text not null references operations(id) on delete cascade,
-            operation_version integer not null,
-            status text not null,
-            risk_level text not null,
-            request_payload_json jsonb not null,
-            response_payload_json jsonb null,
-            created_at timestamptz not null,
-            expires_at timestamptz not null,
-            decided_at timestamptz null,
-            decided_by_key_id text null references platform_api_keys(id) on delete set null,
-            decision_note text null
-        )",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query("alter table approval_requests add column if not exists execution_started_at timestamptz null")
-        .execute(&mut **transaction)
-        .await?;
-    query("alter table approval_requests add column if not exists execution_attempts integer not null default 0")
-        .execute(&mut **transaction)
-        .await?;
-    query("alter table approval_requests add column if not exists request_fingerprint text null")
-        .execute(&mut **transaction)
-        .await?;
-    query(
-        "create unique index if not exists approval_requests_pending_fingerprint_idx
-         on approval_requests(agent_id, operation_id, operation_version, request_fingerprint)
-         where status = 'pending' and request_fingerprint is not null",
-    )
-    .execute(&mut **transaction)
-    .await?;
-    query(
-        "create index if not exists approval_requests_agent_status_idx
-         on approval_requests(workspace_id, agent_id, status, expires_at)",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create table if not exists invocation_logs (
-            id text primary key,
-            workspace_id text not null references workspaces(id) on delete cascade,
-            agent_id text null references agents(id) on delete set null,
-            operation_id text not null references operations(id) on delete cascade,
-            source text not null,
-            level text not null,
-            status text not null,
-            tool_name text not null,
-            message text not null,
-            request_id text null,
-            status_code integer null,
-            duration_ms bigint not null,
-            error_kind text null,
-            request_preview_json jsonb not null,
-            response_preview_json jsonb not null,
-            created_at timestamptz not null
-        )",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create index if not exists invocation_logs_workspace_created_idx on invocation_logs(workspace_id, created_at desc)",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create index if not exists invocation_logs_workspace_operation_created_idx on invocation_logs(workspace_id, operation_id, created_at desc)",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create index if not exists invocation_logs_workspace_agent_created_idx on invocation_logs(workspace_id, agent_id, created_at desc)",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    query(
-        "create table if not exists usage_rollups (
-            workspace_id text not null references workspaces(id) on delete cascade,
-            agent_id text null references agents(id) on delete cascade,
-            operation_id text null references operations(id) on delete cascade,
-            period text not null,
-            calls_total bigint not null,
-            calls_ok bigint not null,
-            calls_error bigint not null,
-            p50_ms bigint not null,
-            p95_ms bigint not null,
-            p99_ms bigint not null,
-            updated_at timestamptz not null
-        )",
-    )
-    .execute(&mut **transaction)
-    .await?;
-
-    Ok(())
-}
+use baseline_v1::{BASELINE_CHECKSUM, BASELINE_VERSION, apply_baseline};
@@ -0,0 +1,926 @@
+use std::fmt;
+
+use sha2::{Digest, Sha256};
+use sqlx::{PgConnection, PgPool, Row, Transaction, query};
+
+use super::schema_guard::{
+    OWNED_RELATIONS, relation_exists, validate_required_relations, validate_schema_fingerprint,
+};
+use super::{BASELINE_CHECKSUM, BASELINE_VERSION, apply_baseline};
+use crate::ext::ExtensionMigration;
+
+const MIGRATION_LOCK_ID: i64 = 0x4352_414E_4B4D_4947;
+const CURRENT_VERSION: i64 = 3;
+const IMPLEMENTED_VERSIONS: &[i64] = &[1, 2, 3];
+const BASELINE_SOURCE_SHA256: &str =
+    "eb1656fc5b4b5be9ee390d237d1d58e4b2274ae5ba9b7ba06a2f3f860dfda675";
+const CONSOLIDATION_SOURCE: &str = include_str!("consolidation_v2.sql");
+const CONSOLIDATION_SOURCE_SHA256: &str =
+    "1908b97ca7fe8a85d146b0eebf007d5018a9ff406cb099614270f3428ec1db48";
+const REQUEST_TRACE_IDENTITY_SOURCE: &str = include_str!("request_trace_identity_v3.sql");
+const REQUEST_TRACE_IDENTITY_SOURCE_SHA256: &str =
+    "36487625503a8d4d8f18d5771c3c9b6705f845e267acbfcb7244c330f640cd94";
+const BASELINE_RELATIONS: &[&str] = &[
+    "workspaces",
+    "users",
+    "memberships",
+    "user_sessions",
+    "invitation_tokens",
+    "platform_api_keys",
+    "operations",
+    "operation_versions",
+    "published_operations",
+    "operation_samples",
+    "descriptors",
+    "agents",
+    "agent_versions",
+    "published_agents",
+    "agent_operation_bindings",
+    "secrets",
+    "secret_versions",
+    "auth_profiles",
+    "workspace_upstreams",
+    "yaml_import_jobs",
+    "import_jobs",
+    "approval_requests",
+    "invocation_logs",
+    "usage_rollups",
+];
+const CONSOLIDATION_RELATIONS: &[&str] = &[
+    "__crank_migrations",
+    "__crank_migration_legacy_audit",
+    "__crank_mcp_migrations",
+    "mcp_transport_sessions",
+    "__crank_ext_migrations",
+];
+const REGISTERED_EXTENSION_MIGRATIONS: &[(&str, ExtensionMigration)] = &[];
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct MigrationDescriptor {
+    pub version: i64,
+    pub name: &'static str,
+    pub checksum: String,
+    pub source_digest: String,
+    pub phase: &'static str,
+    pub compatibility: &'static str,
+    pub owner: &'static str,
+    pub transactional: bool,
+    pub backfill: BackfillPolicy,
+    pub readable_schema_min: i64,
+    pub readable_schema_max: i64,
+    pub contract_evidence: Option<&'static str>,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum BackfillPolicy {
+    None,
+    Bounded {
+        max_batch_rows: u32,
+        max_batch_ms: u32,
+        resumable: bool,
+    },
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct BackfillBatch {
+    pub cursor: Option<String>,
+    pub max_rows: u32,
+    pub max_ms: u32,
+}
+
+impl BackfillBatch {
+    pub fn validate(&self, policy: BackfillPolicy) -> Result<(), MigrationError> {
+        match policy {
+            BackfillPolicy::Bounded {
+                max_batch_rows,
+                max_batch_ms,
+                resumable: true,
+            } if (1..=max_batch_rows).contains(&self.max_rows)
+                && (1..=max_batch_ms).contains(&self.max_ms)
+                && self
+                    .cursor
+                    .as_ref()
+                    .is_none_or(|cursor| cursor.len() <= 256) =>
+            {
+                Ok(())
+            }
+            _ => Err(MigrationError::new(
+                "invalid_contract",
+                "contract.backfill",
+                None,
+                "contact_operator",
+            )),
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum MigrationPreflight {
+    Current { version: i64 },
+    MigrationRequired { current: i64, target: i64 },
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum MigrationApplyResult {
+    Applied { from: i64, to: i64 },
+    AlreadyCurrent { version: i64 },
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct MigrationError {
+    code: &'static str,
+    stage: &'static str,
+    version: Option<i64>,
+    recovery: &'static str,
+}
+
+impl MigrationError {
+    pub(super) fn new(
+        code: &'static str,
+        stage: &'static str,
+        version: Option<i64>,
+        recovery: &'static str,
+    ) -> Self {
+        Self {
+            code,
+            stage,
+            version,
+            recovery,
+        }
+    }
+
+    pub(super) fn storage(stage: &'static str) -> Self {
+        Self::new("storage_unavailable", stage, None, "contact_operator")
+    }
+
+    pub fn code(&self) -> &'static str {
+        self.code
+    }
+
+    pub fn stage(&self) -> &'static str {
+        self.stage
+    }
+
+    pub fn version(&self) -> Option<i64> {
+        self.version
+    }
+
+    pub fn recovery(&self) -> &'static str {
+        self.recovery
+    }
+}
+
+impl fmt::Display for MigrationError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(
+            formatter,
+            "migration_error code={} stage={} version={} recovery={}",
+            self.code,
+            self.stage,
+            self.version
+                .map_or_else(|| "none".to_owned(), |value| value.to_string()),
+            self.recovery
+        )
+    }
+}
+
+impl std::error::Error for MigrationError {}
+
+pub struct MigrationAuthority;
+
+impl MigrationAuthority {
+    pub fn registered_extension_migrations() -> &'static [(&'static str, ExtensionMigration)] {
+        REGISTERED_EXTENSION_MIGRATIONS
+    }
+
+    pub fn sequence() -> Vec<MigrationDescriptor> {
+        vec![
+            MigrationDescriptor {
+                version: i64::from(BASELINE_VERSION),
+                name: "community-baseline-v1",
+                checksum: BASELINE_CHECKSUM.to_owned(),
+                source_digest: BASELINE_SOURCE_SHA256.to_owned(),
+                phase: "expand",
+                compatibility: "legacy-baseline",
+                owner: "crank-registry",
+                transactional: true,
+                backfill: BackfillPolicy::None,
+                readable_schema_min: 1,
+                readable_schema_max: 1,
+                contract_evidence: None,
+            },
+            MigrationDescriptor {
+                version: 2,
+                name: "legacy-consolidation-v2",
+                checksum: CONSOLIDATION_SOURCE_SHA256.to_owned(),
+                source_digest: CONSOLIDATION_SOURCE_SHA256.to_owned(),
+                phase: "expand",
+                compatibility: "n-minus-one-readable",
+                owner: "crank-registry",
+                transactional: true,
+                backfill: BackfillPolicy::None,
+                readable_schema_min: 1,
+                readable_schema_max: 2,
+                contract_evidence: None,
+            },
+            MigrationDescriptor {
+                version: 3,
+                name: "request-trace-identity-v3",
+                checksum: REQUEST_TRACE_IDENTITY_SOURCE_SHA256.to_owned(),
+                source_digest: REQUEST_TRACE_IDENTITY_SOURCE_SHA256.to_owned(),
+                phase: "expand",
+                compatibility: "n-minus-one-readable",
+                owner: "crank-registry",
+                transactional: true,
+                backfill: BackfillPolicy::None,
+                readable_schema_min: 2,
+                readable_schema_max: 3,
+                contract_evidence: None,
+            },
+        ]
+    }
+
+    pub fn validate_sequence() -> Result<(), MigrationError> {
+        validate_descriptors(&Self::sequence())
+    }
+
+    pub async fn preflight(pool: &PgPool) -> Result<MigrationPreflight, MigrationError> {
+        Self::validate_sequence()?;
+        let mut connection = pool
+            .acquire()
+            .await
+            .map_err(|_| MigrationError::storage("preflight.connect"))?;
+        inspect(&mut connection).await
+    }
+
+    pub async fn require_current(pool: &PgPool) -> Result<(), MigrationError> {
+        match Self::preflight(pool).await? {
+            MigrationPreflight::Current { .. } => Ok(()),
+            MigrationPreflight::MigrationRequired { current: 0, .. } => Err(MigrationError::new(
+                "schema_missing",
+                "preflight.compatibility",
+                Some(0),
+                "run_controlled_migration",
+            )),
+            MigrationPreflight::MigrationRequired { current, .. } => Err(MigrationError::new(
+                "migration_required",
+                "preflight.compatibility",
+                Some(current),
+                "run_controlled_migration",
+            )),
+        }
+    }
+
+    pub async fn apply(pool: &PgPool) -> Result<MigrationApplyResult, MigrationError> {
+        Self::validate_sequence()?;
+        let mut transaction = pool
+            .begin()
+            .await
+            .map_err(|_| MigrationError::storage("apply.begin"))?;
+        query("set local lock_timeout = '30s'")
+            .execute(&mut *transaction)
+            .await
+            .map_err(|_| MigrationError::storage("apply.lock_policy"))?;
+        query("select pg_advisory_xact_lock($1)")
+            .bind(MIGRATION_LOCK_ID)
+            .execute(&mut *transaction)
+            .await
+            .map_err(|error| {
+                if error
+                    .as_database_error()
+                    .and_then(|database| database.code())
+                    .is_some_and(|code| matches!(code.as_ref(), "55P03" | "57014"))
+                {
+                    MigrationError::new("lock_timeout", "apply.lock", None, "run_preflight")
+                } else {
+                    MigrationError::storage("apply.lock")
+                }
+            })?;
+
+        let before = inspect(&mut transaction).await?;
+        let from = match before {
+            MigrationPreflight::Current { version } => {
+                transaction
+                    .commit()
+                    .await
+                    .map_err(|_| MigrationError::storage("apply.commit"))?;
+                return Ok(MigrationApplyResult::AlreadyCurrent { version });
+            }
+            MigrationPreflight::MigrationRequired { current, .. } => current,
+        };
+
+        if from == 0 {
+            create_core_ledger(&mut transaction).await?;
+            apply_baseline(&mut transaction).await.map_err(|_| {
+                MigrationError::new(
+                    "apply_failed",
+                    "apply.baseline",
+                    Some(1),
+                    "restore_known_good_backup",
+                )
+            })?;
+            query(
+                "insert into __crank_core_migrations (version, description, checksum)
+                 values (1, 'community baseline', $1)",
+            )
+            .bind(BASELINE_CHECKSUM)
+            .execute(&mut *transaction)
+            .await
+            .map_err(|_| {
+                MigrationError::new(
+                    "apply_failed",
+                    "apply.baseline_ledger",
+                    Some(1),
+                    "restore_known_good_backup",
+                )
+            })?;
+        }
+
+        if from < 2 {
+            apply_consolidation(&mut transaction).await?;
+        }
+        if from < 3 {
+            apply_request_trace_identity(&mut transaction).await?;
+        }
+
+        transaction
+            .commit()
+            .await
+            .map_err(|_| MigrationError::storage("apply.commit"))?;
+        Ok(MigrationApplyResult::Applied {
+            from,
+            to: CURRENT_VERSION,
+        })
+    }
+}
+
+fn sha256_hex(bytes: &[u8]) -> String {
+    format!("{:x}", Sha256::digest(bytes))
+}
+
+#[cfg(test)]
+fn baseline_source_digest() -> String {
+    let source = include_str!("baseline_v1.rs");
+    let (_, baseline) = source
+        .split_once("// baseline-v1:start\n")
+        .expect("baseline start marker must exist");
+    let (baseline, _) = baseline
+        .split_once("// baseline-v1:end")
+        .expect("baseline end marker must exist");
+    sha256_hex(baseline.as_bytes())
+}
+
+fn validate_descriptors(descriptors: &[MigrationDescriptor]) -> Result<(), MigrationError> {
+    if descriptors.is_empty() || descriptors.len() > 1_024 {
+        return Err(MigrationError::new(
+            "invalid_contract",
+            "contract.sequence",
+            None,
+            "contact_operator",
+        ));
+    }
+    for (index, descriptor) in descriptors.iter().enumerate() {
+        let expected_version = i64::try_from(index + 1).unwrap_or(i64::MAX);
+        let valid_name = !descriptor.name.is_empty()
+            && descriptor.name.len() <= 128
+            && descriptor
+                .name
+                .bytes()
+                .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-')
+            && !descriptors[..index]
+                .iter()
+                .any(|prior| prior.name == descriptor.name);
+        let valid_source_digest = descriptor.source_digest.len() == 64
+            && descriptor
+                .source_digest
+                .bytes()
+                .all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase());
+        let valid_checksum = if descriptor.version == 1 {
+            descriptor.checksum == BASELINE_CHECKSUM
+        } else {
+            descriptor.checksum == descriptor.source_digest
+        };
+        let valid_window = descriptor.readable_schema_min >= 1
+            && descriptor.readable_schema_min <= descriptor.readable_schema_max
+            && descriptor.readable_schema_max <= descriptor.version;
+        let valid_phase = match descriptor.phase {
+            "expand" => descriptor.backfill == BackfillPolicy::None,
+            "migrate" => matches!(
+                descriptor.backfill,
+                BackfillPolicy::Bounded {
+                    max_batch_rows: 1..=10_000,
+                    max_batch_ms: 1..=60_000,
+                    resumable: true,
+                }
+            ),
+            "contract" => {
+                descriptor.compatibility == "window-closed"
+                    && descriptor.contract_evidence.is_some_and(|evidence| {
+                        !evidence.is_empty()
+                            && evidence.len() <= 256
+                            && !evidence.starts_with('/')
+                            && !evidence.contains("..")
+                    })
+                    && descriptor.backfill == BackfillPolicy::None
+            }
+            _ => false,
+        };
+        let valid_compatibility = matches!(
+            descriptor.compatibility,
+            "legacy-baseline" | "n-minus-one-readable" | "window-open" | "window-closed"
+        );
+        let valid_owner = !descriptor.owner.is_empty()
+            && descriptor.owner.len() <= 128
+            && descriptor
+                .owner
+                .bytes()
+                .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-');
+        if descriptor.version != expected_version
+            || !valid_name
+            || !valid_source_digest
+            || !valid_checksum
+            || !valid_phase
+            || !valid_compatibility
+            || !valid_owner
+            || !valid_window
+            || !descriptor.transactional
+        {
+            return Err(MigrationError::new(
+                "invalid_contract",
+                "contract.sequence",
+                Some(descriptor.version),
+                "contact_operator",
+            ));
+        }
+    }
+    if descriptors.len() != usize::try_from(CURRENT_VERSION).unwrap_or_default()
+        || descriptors
+            .iter()
+            .map(|descriptor| descriptor.version)
+            .ne(IMPLEMENTED_VERSIONS.iter().copied())
+        || sha256_hex(CONSOLIDATION_SOURCE.as_bytes()) != CONSOLIDATION_SOURCE_SHA256
+        || sha256_hex(REQUEST_TRACE_IDENTITY_SOURCE.as_bytes())
+            != REQUEST_TRACE_IDENTITY_SOURCE_SHA256
+    {
+        return Err(MigrationError::new(
+            "invalid_contract",
+            "contract.implementation",
+            Some(CURRENT_VERSION),
+            "contact_operator",
+        ));
+    }
+    Ok(())
+}
+
+async fn inspect(connection: &mut PgConnection) -> Result<MigrationPreflight, MigrationError> {
+    let core_exists = relation_exists(connection, "__crank_core_migrations").await?;
+    let canonical_exists = relation_exists(connection, "__crank_migrations").await?;
+
+    if !core_exists {
+        let mut owned_exists = canonical_exists;
+        for relation in OWNED_RELATIONS {
+            owned_exists |= relation_exists(connection, relation).await?;
+        }
+        if owned_exists {
+            return Err(MigrationError::new(
+                "partial_sequence",
+                "preflight.core",
+                None,
+                "restore_known_good_backup",
+            ));
+        }
+        inspect_optional_legacy(connection).await?;
+        return Ok(MigrationPreflight::MigrationRequired {
+            current: 0,
+            target: CURRENT_VERSION,
+        });
+    }
+
+    validate_core_ledger(connection).await?;
+    validate_required_relations(connection, BASELINE_RELATIONS, 1).await?;
+    inspect_optional_legacy(connection).await?;
+
+    if !canonical_exists {
+        return Ok(MigrationPreflight::MigrationRequired {
+            current: 1,
+            target: CURRENT_VERSION,
+        });
+    }
+
+    let descriptors = MigrationAuthority::sequence();
+    let rows = query("select version, name, checksum, phase, compatibility from __crank_migrations order by version limit 1025")
+        .fetch_all(&mut *connection)
+        .await
+        .map_err(|_| MigrationError::storage("preflight.canonical"))?;
+    if rows.is_empty() {
+        return Err(MigrationError::new(
+            "partial_sequence",
+            "preflight.canonical",
+            None,
+            "restore_known_good_backup",
+        ));
+    }
+    for (index, row) in rows.iter().enumerate() {
+        let version = row
+            .try_get::<i64, _>("version")
+            .map_err(|_| MigrationError::storage("preflight.canonical"))?;
+        if version > CURRENT_VERSION {
+            return Err(MigrationError::new(
+                "future_version",
+                "preflight.canonical",
+                Some(version),
+                "install_matching_application",
+            ));
+        }
+        let Some(expected) = descriptors.get(index) else {
+            return Err(MigrationError::new(
+                "future_version",
+                "preflight.canonical",
+                Some(version),
+                "install_matching_application",
+            ));
+        };
+        if version != expected.version {
+            return Err(MigrationError::new(
+                "partial_sequence",
+                "preflight.canonical",
+                Some(version),
+                "restore_known_good_backup",
+            ));
+        }
+        let checksum = row
+            .try_get::<String, _>("checksum")
+            .map_err(|_| MigrationError::storage("preflight.canonical"))?;
+        if checksum != expected.checksum {
+            return Err(MigrationError::new(
+                "checksum_mismatch",
+                "preflight.canonical",
+                Some(version),
+                "restore_known_good_backup",
+            ));
+        }
+        let name = row
+            .try_get::<String, _>("name")
+            .map_err(|_| MigrationError::storage("preflight.canonical"))?;
+        let phase = row
+            .try_get::<String, _>("phase")
+            .map_err(|_| MigrationError::storage("preflight.canonical"))?;
+        let compatibility = row
+            .try_get::<String, _>("compatibility")
+            .map_err(|_| MigrationError::storage("preflight.canonical"))?;
+        if name != expected.name
+            || phase != expected.phase
+            || compatibility != expected.compatibility
+        {
+            return Err(MigrationError::new(
+                "checksum_mismatch",
+                "preflight.metadata",
+                Some(version),
+                "restore_known_good_backup",
+            ));
+        }
+    }
+
+    let current = rows
+        .last()
+        .and_then(|row| row.try_get::<i64, _>("version").ok())
+        .ok_or_else(|| MigrationError::storage("preflight.canonical"))?;
+    if rows.len() != usize::try_from(current).unwrap_or_default() {
+        return Err(MigrationError::new(
+            "partial_sequence",
+            "preflight.canonical",
+            Some(current),
+            "restore_known_good_backup",
+        ));
+    }
+    validate_schema_fingerprint(connection, current).await?;
+    if current < CURRENT_VERSION {
+        Ok(MigrationPreflight::MigrationRequired {
+            current,
+            target: CURRENT_VERSION,
+        })
+    } else {
+        validate_required_relations(connection, CONSOLIDATION_RELATIONS, CURRENT_VERSION).await?;
+        validate_schema_fingerprint(connection, CURRENT_VERSION).await?;
+        validate_legacy_audit(connection).await?;
+        Ok(MigrationPreflight::Current { version: current })
+    }
+}
+
+async fn validate_core_ledger(connection: &mut PgConnection) -> Result<(), MigrationError> {
+    let rows = query("select version, description, checksum from __crank_core_migrations order by version limit 2")
+        .fetch_all(connection)
+        .await
+        .map_err(|_| MigrationError::storage("preflight.core"))?;
+    if rows.len() != 1 {
+        return Err(MigrationError::new(
+            "partial_sequence",
+            "preflight.core",
+            None,
+            "restore_known_good_backup",
+        ));
+    }
+    let version = rows[0]
+        .try_get::<i32, _>("version")
+        .map_err(|_| MigrationError::storage("preflight.core"))?;
+    let checksum = rows[0]
+        .try_get::<String, _>("checksum")
+        .map_err(|_| MigrationError::storage("preflight.core"))?;
+    let description = rows[0]
+        .try_get::<String, _>("description")
+        .map_err(|_| MigrationError::storage("preflight.core"))?;
+    if version != BASELINE_VERSION
+        || description != "community baseline"
+        || checksum != BASELINE_CHECKSUM
+    {
+        return Err(MigrationError::new(
+            "checksum_mismatch",
+            "preflight.core",
+            Some(i64::from(version)),
+            "restore_known_good_backup",
+        ));
+    }
+    Ok(())
+}
+
+async fn inspect_optional_legacy(connection: &mut PgConnection) -> Result<(), MigrationError> {
+    let mcp_ledger = relation_exists(connection, "__crank_mcp_migrations").await?;
+    let mcp_sessions = relation_exists(connection, "mcp_transport_sessions").await?;
+    if mcp_ledger != mcp_sessions {
+        return Err(MigrationError::new(
+            "legacy_conflict",
+            "preflight.legacy_mcp",
+            None,
+            "restore_known_good_backup",
+        ));
+    }
+    if mcp_ledger {
+        let rows =
+            query("select version, checksum from __crank_mcp_migrations order by version limit 2")
+                .fetch_all(&mut *connection)
+                .await
+                .map_err(|_| MigrationError::storage("preflight.legacy_mcp"))?;
+        if rows.len() != 1
+            || rows[0].try_get::<i32, _>("version").ok() != Some(1)
+            || rows[0].try_get::<String, _>("checksum").ok().as_deref()
+                != Some("mcp-transport-sessions-v1")
+        {
+            return Err(MigrationError::new(
+                "legacy_conflict",
+                "preflight.legacy_mcp",
+                None,
+                "restore_known_good_backup",
+            ));
+        }
+    }
+    if relation_exists(connection, "__crank_ext_migrations").await? {
+        let count = query("select count(*)::bigint as count from __crank_ext_migrations")
+            .fetch_one(&mut *connection)
+            .await
+            .map_err(|_| MigrationError::storage("preflight.legacy_extension"))?
+            .try_get::<i64, _>("count")
+            .map_err(|_| MigrationError::storage("preflight.legacy_extension"))?;
+        if count > 1_000 {
+            return Err(MigrationError::new(
+                "legacy_conflict",
+                "preflight.legacy_extension",
+                None,
+                "contact_operator",
+            ));
+        }
+        if count > 0 {
+            let checksum_column = query(
+                "select exists (
+                    select 1 from information_schema.columns
+                    where table_schema = current_schema()
+                      and table_name = '__crank_ext_migrations'
+                      and column_name = 'checksum'
+                 ) as present",
+            )
+            .fetch_one(&mut *connection)
+            .await
+            .map_err(|_| MigrationError::storage("preflight.legacy_extension"))?
+            .try_get::<bool, _>("present")
+            .map_err(|_| MigrationError::storage("preflight.legacy_extension"))?;
+            if !checksum_column {
+                return Err(MigrationError::new(
+                    "legacy_conflict",
+                    "preflight.legacy_extension",
+                    None,
+                    "contact_operator",
+                ));
+            }
+            let rows = query(
+                "select extension_name, version, checksum
+                 from __crank_ext_migrations
+                 order by extension_name, version
+                 limit 1001",
+            )
+            .fetch_all(&mut *connection)
+            .await
+            .map_err(|_| MigrationError::storage("preflight.legacy_extension"))?;
+            for row in rows {
+                let name = row
+                    .try_get::<String, _>("extension_name")
+                    .map_err(|_| MigrationError::storage("preflight.legacy_extension"))?;
+                let version = row
+                    .try_get::<i32, _>("version")
+                    .map_err(|_| MigrationError::storage("preflight.legacy_extension"))?;
+                let checksum = row
+                    .try_get::<Option<String>, _>("checksum")
+                    .map_err(|_| MigrationError::storage("preflight.legacy_extension"))?;
+                let registered = MigrationAuthority::registered_extension_migrations()
+                    .iter()
+                    .any(|(registered_name, descriptor)| {
+                        *registered_name == name
+                            && descriptor.version == u32::try_from(version).unwrap_or_default()
+                            && checksum.as_deref() == Some(descriptor.checksum)
+                    });
+                if !registered {
+                    return Err(MigrationError::new(
+                        "legacy_conflict",
+                        "preflight.legacy_extension",
+                        Some(i64::from(version)),
+                        "contact_operator",
+                    ));
+                }
+            }
+        }
+    }
+    Ok(())
+}
+
+async fn validate_legacy_audit(connection: &mut PgConnection) -> Result<(), MigrationError> {
+    let rows = query(
+        "select source, source_version, source_checksum
+         from __crank_migration_legacy_audit
+         order by source, source_version
+         limit 1002",
+    )
+    .fetch_all(&mut *connection)
+    .await
+    .map_err(|_| MigrationError::storage("preflight.legacy_audit"))?;
+    if rows.len() > 1001 {
+        return Err(MigrationError::new(
+            "legacy_conflict",
+            "preflight.legacy_audit",
+            None,
+            "contact_operator",
+        ));
+    }
+    for row in rows {
+        let source = row
+            .try_get::<String, _>("source")
+            .map_err(|_| MigrationError::storage("preflight.legacy_audit"))?;
+        let version = row
+            .try_get::<i64, _>("source_version")
+            .map_err(|_| MigrationError::storage("preflight.legacy_audit"))?;
+        let checksum = row
+            .try_get::<String, _>("source_checksum")
+            .map_err(|_| MigrationError::storage("preflight.legacy_audit"))?;
+        let valid = (source == "core" && version == 1 && checksum == BASELINE_CHECKSUM)
+            || (source == "mcp-session" && version == 1 && checksum == "mcp-transport-sessions-v1")
+            || source.strip_prefix("extension:").is_some_and(|name| {
+                MigrationAuthority::registered_extension_migrations()
+                    .iter()
+                    .any(|(registered_name, descriptor)| {
+                        *registered_name == name
+                            && i64::from(descriptor.version) == version
+                            && descriptor.checksum == checksum
+                    })
+            });
+        if !valid {
+            return Err(MigrationError::new(
+                "legacy_conflict",
+                "preflight.legacy_audit",
+                Some(version),
+                "restore_known_good_backup",
+            ));
+        }
+    }
+    Ok(())
+}
+
+async fn create_core_ledger(
+    transaction: &mut Transaction<'_, sqlx::Postgres>,
+) -> Result<(), MigrationError> {
+    query(
+        "create table __crank_core_migrations (
+            version integer primary key,
+            description text not null,
+            checksum text not null,
+            applied_at timestamptz not null default now()
+        )",
+    )
+    .execute(&mut **transaction)
+    .await
+    .map_err(|_| {
+        MigrationError::new(
+            "apply_failed",
+            "apply.core_ledger",
+            Some(1),
+            "restore_known_good_backup",
+        )
+    })?;
+    Ok(())
+}
+
+async fn apply_consolidation(
+    transaction: &mut Transaction<'_, sqlx::Postgres>,
+) -> Result<(), MigrationError> {
+    sqlx::raw_sql(CONSOLIDATION_SOURCE)
+        .execute(&mut **transaction)
+        .await
+        .map_err(|_| {
+            MigrationError::new(
+                "apply_failed",
+                "apply.consolidation",
+                Some(2),
+                "restore_known_good_backup",
+            )
+        })?;
+    for (name, extension) in MigrationAuthority::registered_extension_migrations() {
+        query(
+            "insert into __crank_migration_legacy_audit
+                (source, source_version, source_checksum)
+             select 'extension:' || $1, $2, $3
+             from __crank_ext_migrations
+             where extension_name = $1 and version = $2 and checksum = $3",
+        )
+        .bind(name)
+        .bind(i64::from(extension.version))
+        .bind(extension.checksum)
+        .execute(&mut **transaction)
+        .await
+        .map_err(|_| {
+            MigrationError::new(
+                "apply_failed",
+                "apply.extension_audit",
+                Some(2),
+                "restore_known_good_backup",
+            )
+        })?;
+    }
+    let descriptor = &MigrationAuthority::sequence()[1];
+    query(
+        "insert into __crank_migrations (version, name, checksum, phase, compatibility)
+         values ($1, $2, $3, $4, $5)",
+    )
+    .bind(descriptor.version)
+    .bind(descriptor.name)
+    .bind(&descriptor.checksum)
+    .bind(descriptor.phase)
+    .bind(descriptor.compatibility)
+    .execute(&mut **transaction)
+    .await
+    .map_err(|_| {
+        MigrationError::new(
+            "apply_failed",
+            "apply.canonical_ledger",
+            Some(2),
+            "restore_known_good_backup",
+        )
+    })?;
+    Ok(())
+}
+
+async fn apply_request_trace_identity(
+    transaction: &mut Transaction<'_, sqlx::Postgres>,
+) -> Result<(), MigrationError> {
+    sqlx::raw_sql(REQUEST_TRACE_IDENTITY_SOURCE)
+        .execute(&mut **transaction)
+        .await
+        .map_err(|_| {
+            MigrationError::new(
+                "apply_failed",
+                "apply.request_trace_identity",
+                Some(3),
+                "restore_known_good_backup",
+            )
+        })?;
+    let descriptor = &MigrationAuthority::sequence()[2];
+    query(
+        "insert into __crank_migrations (version, name, checksum, phase, compatibility)
+         values ($1, $2, $3, $4, $5)",
+    )
+    .bind(descriptor.version)
+    .bind(descriptor.name)
+    .bind(&descriptor.checksum)
+    .bind(descriptor.phase)
+    .bind(descriptor.compatibility)
+    .execute(&mut **transaction)
+    .await
+    .map_err(|_| {
+        MigrationError::new(
+            "apply_failed",
+            "apply.canonical_ledger",
+            Some(3),
+            "restore_known_good_backup",
+        )
+    })?;
+    Ok(())
+}
+
+#[cfg(test)]
+#[path = "authority_tests.rs"]
+mod tests;
@@ -0,0 +1,115 @@
+use super::*;
+
+#[test]
+fn sequence_is_deterministic_and_append_only() {
+    let first = MigrationAuthority::sequence();
+    let second = MigrationAuthority::sequence();
+    assert_eq!(first, second);
+    MigrationAuthority::validate_sequence().unwrap();
+    assert_eq!(
+        first.iter().map(|item| item.version).collect::<Vec<_>>(),
+        vec![1, 2, 3]
+    );
+    assert_eq!(first[0].checksum, "crank-community-baseline-v1");
+    assert_eq!(first[0].source_digest, BASELINE_SOURCE_SHA256);
+    assert_eq!(
+        baseline_source_digest(),
+        BASELINE_SOURCE_SHA256,
+        "baseline v1 source changed; add a new migration instead"
+    );
+    assert_eq!(first[1].checksum.len(), 64);
+    assert!(
+        first[1]
+            .checksum
+            .bytes()
+            .all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase())
+    );
+}
+
+#[test]
+fn invalid_gap_checksum_phase_and_unbounded_backfill_are_rejected() {
+    let base = MigrationAuthority::sequence();
+    for invalid in [
+        {
+            let mut value = base.clone();
+            value[1].version = 3;
+            value
+        },
+        {
+            let mut value = base.clone();
+            value[1].checksum = "0".repeat(64);
+            value
+        },
+        {
+            let mut value = base.clone();
+            value[1].phase = "unknown";
+            value
+        },
+        {
+            let mut value = base.clone();
+            value[1].name = value[0].name;
+            value
+        },
+        {
+            let mut value = base.clone();
+            value[1].transactional = false;
+            value
+        },
+        {
+            let mut value = base.clone();
+            value[1].phase = "migrate";
+            value[1].backfill = BackfillPolicy::Bounded {
+                max_batch_rows: 10_001,
+                max_batch_ms: 60_001,
+                resumable: false,
+            };
+            value
+        },
+        {
+            let mut value = base.clone();
+            value[1].phase = "contract";
+            value[1].compatibility = "window-closed";
+            value[1].contract_evidence = None;
+            value
+        },
+    ] {
+        assert_eq!(
+            validate_descriptors(&invalid).unwrap_err().code(),
+            "invalid_contract"
+        );
+    }
+}
+
+#[test]
+fn backfill_batches_are_bounded_and_resumable() {
+    let policy = BackfillPolicy::Bounded {
+        max_batch_rows: 100,
+        max_batch_ms: 1_000,
+        resumable: true,
+    };
+    BackfillBatch {
+        cursor: Some("next-100".to_owned()),
+        max_rows: 100,
+        max_ms: 1_000,
+    }
+    .validate(policy)
+    .unwrap();
+    assert!(
+        BackfillBatch {
+            cursor: None,
+            max_rows: 101,
+            max_ms: 1_000,
+        }
+        .validate(policy)
+        .is_err()
+    );
+}
+
+#[test]
+fn diagnostic_is_bounded_and_does_not_echo_storage_details() {
+    let error = MigrationError::storage("preflight.connect");
+    let rendered = error.to_string();
+    assert!(rendered.len() < 512);
+    assert!(!rendered.contains("postgres://"));
+    assert_eq!(error.code(), "storage_unavailable");
+}
@@ -0,0 +1,673 @@
+use sqlx::{Postgres, Transaction, query};
+
+pub(super) const BASELINE_VERSION: i32 = 1;
+pub(super) const BASELINE_CHECKSUM: &str = "crank-community-baseline-v1";
+
+// baseline-v1:start
+pub(super) async fn apply_baseline(
+    transaction: &mut Transaction<'_, Postgres>,
+) -> Result<(), sqlx::Error> {
+    query(
+        "create table if not exists workspaces (
+            id text primary key,
+            slug text not null unique,
+            display_name text not null,
+            status text not null,
+            settings_json jsonb not null default '{}'::jsonb,
+            created_at timestamptz not null,
+            updated_at timestamptz not null
+        )",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create table if not exists users (
+            id text primary key,
+            email text not null unique,
+            display_name text not null,
+            password_hash text null,
+            status text not null,
+            created_at timestamptz not null
+        )",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query("alter table users add column if not exists password_hash text null")
+        .execute(&mut **transaction)
+        .await?;
+
+    query(
+        "insert into users (
+            id,
+            email,
+            display_name,
+            status,
+            created_at
+        ) values (
+            'user_default_owner',
+            'owner@crank.local',
+            'Workspace Owner',
+            'active',
+            now()
+        )
+        on conflict (id) do nothing",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create table if not exists memberships (
+            workspace_id text not null references workspaces(id) on delete cascade,
+            user_id text not null references users(id) on delete cascade,
+            role text not null,
+            created_at timestamptz not null,
+            primary key (workspace_id, user_id)
+        )",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create table if not exists user_sessions (
+            id text primary key,
+            user_id text not null references users(id) on delete cascade,
+            current_workspace_id text null references workspaces(id) on delete set null,
+            secret_hash text not null,
+            status text not null,
+            expires_at timestamptz not null,
+            last_seen_at timestamptz null,
+            created_at timestamptz not null
+        )",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "alter table user_sessions
+         add column if not exists current_workspace_id text null references workspaces(id) on delete set null",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "insert into workspaces (
+            id,
+            slug,
+            display_name,
+            status,
+            settings_json,
+            created_at,
+            updated_at
+        ) values (
+            'ws_default',
+            'default',
+            'Default Workspace',
+            'active',
+            '{}'::jsonb,
+            now(),
+            now()
+        )
+        on conflict (id) do nothing",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "insert into memberships (
+            workspace_id,
+            user_id,
+            role,
+            created_at
+        ) values (
+            'ws_default',
+            'user_default_owner',
+            'owner',
+            now()
+        )
+        on conflict (workspace_id, user_id) do nothing",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create table if not exists invitation_tokens (
+            id text primary key,
+            workspace_id text not null references workspaces(id) on delete cascade,
+            email text not null,
+            role text not null,
+            status text not null,
+            token_hash text not null,
+            expires_at timestamptz not null,
+            created_at timestamptz not null
+        )",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create table if not exists platform_api_keys (
+            id text primary key,
+            workspace_id text not null references workspaces(id) on delete cascade,
+            agent_id text null,
+            name text not null,
+            prefix text not null,
+            secret_hash text not null,
+            key_kind text not null default 'mcp_client',
+            scopes_json jsonb not null,
+            status text not null,
+            created_at timestamptz not null,
+            last_used_at timestamptz null,
+            revoked_at timestamptz null,
+            expires_at timestamptz null,
+            allowed_origins_json jsonb not null default '[]'::jsonb
+        )",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create unique index if not exists platform_api_keys_workspace_name_idx on platform_api_keys(workspace_id, name)",
+    )
+    .execute(&mut **transaction)
+    .await?;
+    query("alter table platform_api_keys add column if not exists agent_id text null")
+        .execute(&mut **transaction)
+        .await?;
+    query(
+        "alter table platform_api_keys add column if not exists key_kind text not null default 'mcp_client'",
+    )
+    .execute(&mut **transaction)
+    .await?;
+    query("alter table platform_api_keys add column if not exists expires_at timestamptz null")
+        .execute(&mut **transaction)
+        .await?;
+    query(
+        "alter table platform_api_keys add column if not exists allowed_origins_json jsonb not null default '[]'::jsonb",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "insert into workspaces (
+            id,
+            slug,
+            display_name,
+            status,
+            settings_json,
+            created_at,
+            updated_at
+        ) values (
+            'ws_default',
+            'default',
+            'Default Workspace',
+            'active',
+            '{}'::jsonb,
+            now(),
+            now()
+        )
+        on conflict (id) do nothing",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create table if not exists operations (
+            id text primary key,
+            workspace_id text null references workspaces(id) on delete cascade,
+            name text not null,
+            display_name text not null,
+            category text not null default 'general',
+            protocol text not null,
+            security_level text not null default 'standard',
+            status text not null,
+            current_draft_version integer not null default 1,
+            latest_published_version integer null,
+            created_at timestamptz not null,
+            updated_at timestamptz not null,
+            published_at timestamptz null
+        )",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query("alter table operations add column if not exists workspace_id text null references workspaces(id) on delete cascade")
+        .execute(&mut **transaction)
+        .await?;
+    query(
+        "alter table operations add column if not exists category text not null default 'general'",
+    )
+    .execute(&mut **transaction)
+    .await?;
+    query(
+        "alter table operations add column if not exists security_level text not null default 'standard'",
+    )
+    .execute(&mut **transaction)
+    .await?;
+    query("update operations set workspace_id = 'ws_default' where workspace_id is null")
+        .execute(&mut **transaction)
+        .await?;
+    query("alter table operations alter column workspace_id set not null")
+        .execute(&mut **transaction)
+        .await?;
+    query("alter table operations drop constraint if exists operations_name_key")
+        .execute(&mut **transaction)
+        .await?;
+    query(
+        "create unique index if not exists operations_workspace_name_idx on operations(workspace_id, name)",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create table if not exists operation_versions (
+            operation_id text not null references operations(id) on delete cascade,
+            version integer not null,
+            status text not null,
+            target_json jsonb not null,
+            input_schema_json jsonb not null,
+            output_schema_json jsonb not null,
+            input_mapping_json jsonb not null,
+            output_mapping_json jsonb not null,
+            execution_config_json jsonb not null,
+            tool_description_json jsonb not null,
+            samples_json jsonb null,
+            generated_draft_json jsonb null,
+            config_export_json jsonb null,
+            wizard_state_json jsonb null,
+            change_note text null,
+            created_at timestamptz not null,
+            created_by text null,
+            primary key (operation_id, version)
+        )",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query("alter table operation_versions add column if not exists wizard_state_json jsonb null")
+        .execute(&mut **transaction)
+        .await?;
+
+    query(
+        "create table if not exists published_operations (
+            operation_id text primary key references operations(id) on delete cascade,
+            version integer not null,
+            published_at timestamptz not null,
+            published_by text null,
+            foreign key (operation_id, version) references operation_versions(operation_id, version) on delete cascade
+        )",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create table if not exists operation_samples (
+            id text primary key,
+            operation_id text not null references operations(id) on delete cascade,
+            version integer not null,
+            sample_kind text not null,
+            storage_ref text not null,
+            content_type text not null,
+            file_name text null,
+            created_at timestamptz not null,
+            foreign key (operation_id, version) references operation_versions(operation_id, version) on delete cascade
+        )",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create table if not exists descriptors (
+            id text primary key,
+            operation_id text null references operations(id) on delete cascade,
+            version integer null,
+            descriptor_kind text not null,
+            storage_ref text not null,
+            source_name text null,
+            package_index_json jsonb null,
+            created_at timestamptz not null,
+            foreign key (operation_id, version) references operation_versions(operation_id, version) on delete cascade
+        )",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create table if not exists auth_profiles (
+            id text primary key,
+            workspace_id text null references workspaces(id) on delete cascade,
+            name text not null,
+            kind text not null,
+            config_json jsonb not null,
+            created_at timestamptz not null,
+            updated_at timestamptz not null
+        )",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query("alter table auth_profiles add column if not exists workspace_id text null references workspaces(id) on delete cascade")
+        .execute(&mut **transaction)
+        .await?;
+    query("update auth_profiles set workspace_id = 'ws_default' where workspace_id is null")
+        .execute(&mut **transaction)
+        .await?;
+    query("alter table auth_profiles alter column workspace_id set not null")
+        .execute(&mut **transaction)
+        .await?;
+    query("alter table auth_profiles drop constraint if exists auth_profiles_name_key")
+        .execute(&mut **transaction)
+        .await?;
+    query(
+        "create unique index if not exists auth_profiles_workspace_name_idx on auth_profiles(workspace_id, name)",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create table if not exists workspace_upstreams (
+            id text primary key,
+            workspace_id text not null references workspaces(id) on delete cascade,
+            name text not null,
+            base_url text not null,
+            static_headers_json jsonb not null default '{}'::jsonb,
+            auth_profile_id text null references auth_profiles(id) on delete set null,
+            created_at timestamptz not null,
+            updated_at timestamptz not null
+        )",
+    )
+    .execute(&mut **transaction)
+    .await?;
+    query(
+        "create unique index if not exists workspace_upstreams_workspace_name_idx on workspace_upstreams(workspace_id, name)",
+    )
+    .execute(&mut **transaction)
+    .await?;
+    query(
+        "create unique index if not exists workspace_upstreams_workspace_base_auth_idx on workspace_upstreams(workspace_id, base_url, coalesce(auth_profile_id, ''))",
+    )
+    .execute(&mut **transaction)
+    .await?;
+    query(
+        "insert into workspace_upstreams (
+            id,
+            workspace_id,
+            name,
+            base_url,
+            static_headers_json,
+            auth_profile_id,
+            created_at,
+            updated_at
+        )
+        select
+            'upstream_frankfurter_' || w.id,
+            w.id,
+            'Frankfurter',
+            'https://api.frankfurter.dev',
+            '{}'::jsonb,
+            null,
+            now(),
+            now()
+        from workspaces w
+        where not exists (
+            select 1
+            from workspace_upstreams wu
+            where wu.workspace_id = w.id
+              and wu.name = 'Frankfurter'
+        )",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create table if not exists secrets (
+            id text primary key,
+            workspace_id text not null references workspaces(id) on delete cascade,
+            name text not null,
+            kind text not null,
+            status text not null,
+            current_version integer not null,
+            last_used_at timestamptz null,
+            created_at timestamptz not null,
+            updated_at timestamptz not null
+        )",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create unique index if not exists secrets_workspace_name_idx on secrets(workspace_id, name)",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create table if not exists secret_versions (
+            secret_id text not null references secrets(id) on delete cascade,
+            version integer not null,
+            ciphertext text not null,
+            key_version text not null,
+            created_at timestamptz not null,
+            created_by text null references users(id) on delete set null,
+            primary key (secret_id, version)
+        )",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create table if not exists yaml_import_jobs (
+            id text primary key,
+            source_sample_id text null references operation_samples(id) on delete set null,
+            status text not null,
+            format_version text not null,
+            mode text not null,
+            result_operation_id text null references operations(id) on delete set null,
+            result_version integer null,
+            error_text text null,
+            created_at timestamptz not null,
+            finished_at timestamptz null
+        )",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create table if not exists import_jobs (
+            id text primary key,
+            workspace_id text not null references workspaces(id) on delete cascade,
+            kind text not null,
+            source_format text not null,
+            source_version text null,
+            status text not null,
+            preview_payload jsonb not null,
+            created_operation_ids jsonb not null default '[]'::jsonb,
+            error_text text null,
+            created_at timestamptz not null,
+            expires_at timestamptz not null,
+            finished_at timestamptz null
+        )",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create table if not exists agents (
+            id text primary key,
+            workspace_id text not null references workspaces(id) on delete cascade,
+            slug text not null,
+            display_name text not null,
+            description text not null,
+            status text not null,
+            current_draft_version integer not null default 1,
+            latest_published_version integer null,
+            created_at timestamptz not null,
+            updated_at timestamptz not null,
+            published_at timestamptz null
+        )",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create unique index if not exists agents_workspace_slug_idx on agents(workspace_id, slug)",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create table if not exists agent_versions (
+            agent_id text not null references agents(id) on delete cascade,
+            version integer not null,
+            status text not null,
+            instructions_json jsonb not null,
+            tool_selection_policy_json jsonb not null,
+            created_at timestamptz not null,
+            primary key (agent_id, version)
+        )",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create table if not exists agent_operation_bindings (
+            agent_id text not null references agents(id) on delete cascade,
+            agent_version integer not null,
+            operation_id text not null references operations(id) on delete cascade,
+            operation_version integer not null,
+            tool_name text not null,
+            tool_title text not null,
+            tool_description_override text null,
+            enabled boolean not null default true,
+            foreign key (agent_id, agent_version) references agent_versions(agent_id, version) on delete cascade,
+            foreign key (operation_id, operation_version) references operation_versions(operation_id, version) on delete cascade
+        )",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create unique index if not exists agent_bindings_tool_name_idx on agent_operation_bindings(agent_id, agent_version, tool_name)",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create table if not exists published_agents (
+            agent_id text primary key references agents(id) on delete cascade,
+            version integer not null,
+            published_at timestamptz not null,
+            published_by text null,
+            foreign key (agent_id, version) references agent_versions(agent_id, version) on delete cascade
+        )",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create table if not exists approval_requests (
+            id text primary key,
+            workspace_id text not null references workspaces(id) on delete cascade,
+            agent_id text not null references agents(id) on delete cascade,
+            operation_id text not null references operations(id) on delete cascade,
+            operation_version integer not null,
+            status text not null,
+            risk_level text not null,
+            request_payload_json jsonb not null,
+            response_payload_json jsonb null,
+            created_at timestamptz not null,
+            expires_at timestamptz not null,
+            decided_at timestamptz null,
+            decided_by_key_id text null references platform_api_keys(id) on delete set null,
+            decision_note text null
+        )",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query("alter table approval_requests add column if not exists execution_started_at timestamptz null")
+        .execute(&mut **transaction)
+        .await?;
+    query("alter table approval_requests add column if not exists execution_attempts integer not null default 0")
+        .execute(&mut **transaction)
+        .await?;
+    query("alter table approval_requests add column if not exists request_fingerprint text null")
+        .execute(&mut **transaction)
+        .await?;
+    query(
+        "create unique index if not exists approval_requests_pending_fingerprint_idx
+         on approval_requests(agent_id, operation_id, operation_version, request_fingerprint)
+         where status = 'pending' and request_fingerprint is not null",
+    )
+    .execute(&mut **transaction)
+    .await?;
+    query(
+        "create index if not exists approval_requests_agent_status_idx
+         on approval_requests(workspace_id, agent_id, status, expires_at)",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create table if not exists invocation_logs (
+            id text primary key,
+            workspace_id text not null references workspaces(id) on delete cascade,
+            agent_id text null references agents(id) on delete set null,
+            operation_id text not null references operations(id) on delete cascade,
+            source text not null,
+            level text not null,
+            status text not null,
+            tool_name text not null,
+            message text not null,
+            request_id text null,
+            status_code integer null,
+            duration_ms bigint not null,
+            error_kind text null,
+            request_preview_json jsonb not null,
+            response_preview_json jsonb not null,
+            created_at timestamptz not null
+        )",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create index if not exists invocation_logs_workspace_created_idx on invocation_logs(workspace_id, created_at desc)",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create index if not exists invocation_logs_workspace_operation_created_idx on invocation_logs(workspace_id, operation_id, created_at desc)",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create index if not exists invocation_logs_workspace_agent_created_idx on invocation_logs(workspace_id, agent_id, created_at desc)",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    query(
+        "create table if not exists usage_rollups (
+            workspace_id text not null references workspaces(id) on delete cascade,
+            agent_id text null references agents(id) on delete cascade,
+            operation_id text null references operations(id) on delete cascade,
+            period text not null,
+            calls_total bigint not null,
+            calls_ok bigint not null,
+            calls_error bigint not null,
+            p50_ms bigint not null,
+            p95_ms bigint not null,
+            p99_ms bigint not null,
+            updated_at timestamptz not null
+        )",
+    )
+    .execute(&mut **transaction)
+    .await?;
+
+    Ok(())
+}
+// baseline-v1:end
@@ -0,0 +1,84 @@
+create temporary table __crank_v2_context (
+    had_mcp_ledger boolean not null
+) on commit drop;
+
+insert into __crank_v2_context (had_mcp_ledger)
+values (to_regclass(format('%I.%I', current_schema(), '__crank_mcp_migrations')) is not null);
+
+create table __crank_migrations (
+    version bigint primary key,
+    name text not null unique,
+    checksum text not null,
+    phase text not null,
+    compatibility text not null,
+    applied_at timestamptz not null default now()
+);
+
+create table __crank_migration_legacy_audit (
+    source text not null,
+    source_version bigint not null,
+    source_checksum text not null,
+    imported_at timestamptz not null default now(),
+    primary key (source, source_version)
+);
+
+insert into __crank_migrations (version, name, checksum, phase, compatibility)
+values (
+    1,
+    'community-baseline-v1',
+    'crank-community-baseline-v1',
+    'expand',
+    'legacy-baseline'
+);
+
+insert into __crank_migration_legacy_audit (source, source_version, source_checksum)
+values ('core', 1, 'crank-community-baseline-v1');
+
+create table if not exists __crank_mcp_migrations (
+    version integer primary key,
+    checksum text not null,
+    applied_at timestamptz not null default now()
+);
+
+create table if not exists mcp_transport_sessions (
+    id text primary key,
+    protocol_version text not null,
+    initialized boolean not null default false,
+    supports_elicitation boolean not null default false,
+    workspace_slug text not null,
+    agent_slug text not null,
+    created_at timestamptz not null,
+    updated_at timestamptz not null,
+    expires_at timestamptz null
+);
+
+alter table mcp_transport_sessions
+    add column if not exists supports_elicitation boolean not null default false;
+alter table mcp_transport_sessions
+    add column if not exists expires_at timestamptz null;
+
+create index if not exists mcp_transport_sessions_workspace_agent_idx
+    on mcp_transport_sessions(workspace_slug, agent_slug, updated_at desc);
+create index if not exists mcp_transport_sessions_expires_at_idx
+    on mcp_transport_sessions(expires_at)
+    where expires_at is not null;
+
+insert into __crank_mcp_migrations (version, checksum)
+values (1, 'mcp-transport-sessions-v1')
+on conflict (version) do nothing;
+
+insert into __crank_migration_legacy_audit (source, source_version, source_checksum)
+select 'mcp-session', 1, 'mcp-transport-sessions-v1'
+from __crank_v2_context
+where had_mcp_ledger;
+
+create table if not exists __crank_ext_migrations (
+    extension_name text not null,
+    version integer not null,
+    checksum text null,
+    applied_at timestamptz not null default now(),
+    primary key (extension_name, version)
+);
+
+alter table __crank_ext_migrations
+    add column if not exists checksum text null;
@@ -0,0 +1,20 @@
+alter table invocation_logs
+    add column trace_id text;
+
+alter table invocation_logs
+    add constraint invocation_logs_trace_id_format_check
+    check (
+        trace_id is null
+        or (
+            trace_id ~ '^[0-9a-f]{32}$'
+            and trace_id <> '00000000000000000000000000000000'
+        )
+    ) not valid;
+
+create index invocation_logs_workspace_request_id_idx
+    on invocation_logs(workspace_id, request_id)
+    where request_id is not null and octet_length(request_id) <= 128;
+
+create index invocation_logs_workspace_trace_id_idx
+    on invocation_logs(workspace_id, trace_id)
+    where trace_id is not null;
--- a/Show More
+++ b/Show More