feat: harden community production foundation through story 1.5

.env.example

@@ -1,46 +1,34 @@
-POSTGRES_DB=crank
+# Deployment-only image and publication settings.
-POSTGRES_USER=crank
+CRANK_ADMIN_API_IMAGE=crank/admin-api:dev
-POSTGRES_PASSWORD=change-me
+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_MASTER_KEY=
-CRANK_MCP_SERVER_IMAGE=crank/mcp-server:dev
+CRANK_BASE_URL=http://localhost:3000
-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_RUNTIME_MAX_CONCURRENT_UNARY=64
-CRANK_RUNTIME_MAX_CONCURRENT_WINDOW=16
+CRANK_CACHE_BACKEND=memory
-CRANK_RUNTIME_MAX_CONCURRENT_SESSIONS=16
+CRANK_CACHE_URL=
-CRANK_RUNTIME_MAX_CONCURRENT_JOBS=16
-# Публичные узлы разрешены по умолчанию. Для внутренних API перечислите
-# допустимые имена или IP через запятую.
 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_ADMIN_BIND=0.0.0.0:3001
-CRANK_SESSION_SECRET=change-me-session-secret
+CRANK_ADMIN_METRICS_BIND=127.0.0.1:9464
-CRANK_PASSWORD_PEPPER=change-me-password-pepper
+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
+CRANK_TRUST_FORWARDED_HEADERS=false
-# admin-api runs behind the bundled nginx (or another trusted reverse proxy).
+CRANK_BOOTSTRAP_ADMIN_EMAIL=
-CRANK_TRUST_FORWARDED_HEADERS=true
+CRANK_BOOTSTRAP_ADMIN_PASSWORD=
-CRANK_BOOTSTRAP_ADMIN_EMAIL=owner@crank.local
-CRANK_BOOTSTRAP_ADMIN_PASSWORD=change-me-admin-password
 CRANK_BOOTSTRAP_ADMIN_DISPLAY_NAME=Crank Owner
-CRANK_DEMO_SEED=true
+CRANK_DEMO_SEED=false
-CRANK_BASE_URL=https://crank.example.com
+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

.gitea/workflows/ci.yml

@@ -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
+      - name: Validate Community deployment manifests
-        run: docker compose -f deploy/community/docker-compose.yml --env-file deploy/community/.env.example config -q
+        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: |

.gitea/workflows/release.yml

@@ -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
+      - name: Validate deployment manifests
-        run: docker compose -f deploy/community/docker-compose.yml --env-file deploy/community/.env.example config -q
+        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 }}' \

.gitignore

@@ -23,3 +23,6 @@ __*.md
 diploma/
 AGENTS.md
 TASKS.md
+
+# BMAD workspace data and generated artifacts
+**/_bmad*/

CONTRIBUTING.md

@@ -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 и документации.

Cargo.lock

@@ -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",

Cargo.toml

@@ -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",

README.md

@@ -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)
 
 ## Участие в разработке
 

apps/admin-api/Cargo.toml

@@ -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" }

apps/admin-api/Dockerfile

@@ -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 \
+RUN --mount=type=cache,id=crank-admin-cargo-registry,target=/usr/local/cargo/registry \
-    --mount=type=cache,target=/usr/local/cargo/git/db \
+    --mount=type=cache,id=crank-admin-cargo-git,target=/usr/local/cargo/git/db \
-    --mount=type=cache,target=/app/target \
+    --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
 

apps/admin-api/src/bin/crank-migrate.rs

@@ -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",
+    ))
+}

apps/admin-api/src/dto.rs

@@ -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,

apps/admin-api/src/error.rs

@@ -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(_) => {
+            RegistryError::Migration(_)
-                Self::internal(value.to_string())
+            | 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,
         })),

apps/admin-api/src/main.rs

@@ -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>> {
+async fn main() -> ExitCode {
-    let observability = crank_observability::init(ObservabilityConfig::from_env(
+    match main_result().await {
-        "admin-api",
+        Ok(()) => ExitCode::SUCCESS,
-        env!("CARGO_PKG_VERSION"),
+        Err(error) => {
-        "admin_api=info,tower_http=info",
+            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 =
+    let metrics_config = MetricsConfig::new(
-        MetricsConfig::from_env("CRANK_ADMIN_METRICS_BIND", "127.0.0.1:9464".parse()?)?;
+        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")?,
+        session_secret: config.session_secret.expose_secret().to_owned(),
-        password_pepper: env::var("CRANK_PASSWORD_PEPPER")?,
+        password_pepper: config.password_pepper.expose_secret().to_owned(),
-        session_ttl_hours: env::var("CRANK_SESSION_TTL_HOURS")
+        session_ttl_hours: config.session_ttl_hours,
-            .ok()
-            .and_then(|value| value.parse::<i64>().ok())
-            .unwrap_or(24),
         cookie_secure: base_url.starts_with("https://"),
         bootstrap_admin: BootstrapAdminConfig {
-            email: env::var("CRANK_BOOTSTRAP_ADMIN_EMAIL")?,
+            email: config.bootstrap_email.clone(),
-            password: env::var("CRANK_BOOTSTRAP_ADMIN_PASSWORD")?,
+            password: config.bootstrap_password.expose_secret().to_owned(),
-            display_name: env::var("CRANK_BOOTSTRAP_ADMIN_DISPLAY_NAME")
+            display_name: config.bootstrap_display_name.clone(),
-                .unwrap_or_else(|_| "Crank Owner".into()),
         },
     };
-    let runtime_limits = RuntimeLimits::from_env()?;
+    let runtime_limits = RuntimeLimits::try_new(
-    let cache_config = RuntimeCacheConfig::from_env()?;
+        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 api_rate_limit = RequestRateLimitConfig::new(
-    let secret_crypto = SecretCrypto::new(&env::var("CRANK_MASTER_KEY")?)?;
+        config.rate_limit.requests_per_second,
-    let outbound_http_policy = crank_runtime::OutboundHttpPolicy::from_env()?;
+        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!(
+    info!(name: "admin.server.listening", bind_address = %config.bind_addr, "admin-api listening");
-        name: "admin.server.listening",
-        bind_address = %socket_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>> {
+fn init_observability(
-    const NAME: &str = "CRANK_INVOCATION_LOG_RETENTION_DAYS";
+    config: &ObservabilitySettings,
-    let value = match env::var(NAME) {
+) -> Result<ObservabilityLifecycle, Box<dyn std::error::Error>> {
-        Ok(raw) => raw.parse::<i64>()?,
+    let identity = ServiceIdentity::try_new(
-        Err(env::VarError::NotPresent) => 30,
+        "admin-api",
-        Err(error) => return Err(error.into()),
+        env!("CARGO_PKG_VERSION"),
-    };
+        config.environment.clone(),
-    if !(1..=MAX_INVOCATION_LOG_RETENTION_DAYS).contains(&value) {
+    )?;
-        return Err(
+    let base = ObservabilityConfig::try_new(
-            format!("{NAME} must be between 1 and {MAX_INVOCATION_LOG_RETENTION_DAYS}").into(),
+        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))
-}

apps/admin-api/src/request_context.rs

@@ -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 {
+    let (request_id, remote_parent) = resolve_correlation(request.headers());
-        request_id: RequestId::resolve_from_headers(request.headers()).into_string(),
-    };
     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(
-        let mut response = next.run(request).instrument(span).await;
+        context.correlation.request_id().to_string(),
-        info!(
+        context.correlation.trace_id().to_string(),
-            name: "admin.request.completed",
+        async move {
-            request_id = %context.request_id,
+            let mut response = next.run(request).instrument(span).await;
-            method = %method,
+            info!(
-            route,
+                name: "admin.request.completed",
-            status = response.status().as_u16(),
+                request_id = %context.correlation.request_id(),
-            "admin request completed"
+                trace_id = %context.correlation.trace_id(),
-        );
+                method = %method,
-        if let Ok(value) = HeaderValue::from_str(&context.request_id) {
+                route,
-            response.headers_mut().insert(REQUEST_ID_HEADER, value);
+                status = response.status().as_u16(),
-        }
+                "admin request completed"
-        response
+            );
-    })
+            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_core::RequestId::is_valid("req_test_123"));
-        assert!(crank_observability::RequestId::is_valid("trace-123/abc"));
+        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_core::RequestId::is_valid(""));
-        assert!(!crank_observability::RequestId::is_valid("bad value"));
+        assert!(!crank_core::RequestId::is_valid("bad value"));
-        assert!(!crank_observability::RequestId::is_valid("bad\nvalue"));
+        assert!(!crank_core::RequestId::is_valid("bad\nvalue"));
     }
 }

apps/admin-api/src/routes/operations.rs

@@ -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)))

apps/admin-api/src/service.rs

@@ -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,
         );

apps/admin-api/src/service/demo.rs

@@ -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,

apps/admin-api/src/service/operations.rs

@@ -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,

apps/admin-api/tests/config_startup.rs

@@ -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);
+}

apps/admin-api/tests/integration.rs

@@ -4,5 +4,6 @@ mod integration {
     mod community_access_usage;
     mod openapi_import;
     mod operations_agents;
+    mod request_context;
     mod secrets_import_auth;
 }

apps/admin-api/tests/integration/common.rs

@@ -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

apps/admin-api/tests/integration/operations_agents.rs

@@ -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 (upstream_base_url, observed_upstream_headers) = spawn_correlation_upstream_server().await;
-    let base_url = spawn_admin_api(build_test_app(registry, storage_root)).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")]

apps/admin-api/tests/integration/request_context.rs

@@ -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))

apps/admin-api/tests/migration_command.rs

@@ -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);
+}

apps/admin-api/tests/unit/error.rs

@@ -13,27 +13,19 @@ fn runtime_test_failure_includes_structured_context() {
     assert_eq!(
         payload["context"],
         json!({
-            "field": "request.headers",
+            "field": "request.headers"
-            "reason": "must be an object"
         })
     );
 }
 
 #[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!(
+    assert_eq!(context, None);
-        context,
-        json!({
-            "operation": "decode secret envelope",
-            "details": "bad base64"
-        })
-    );
 }
 
 #[test]

apps/mcp-server/Cargo.toml

@@ -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" }

apps/mcp-server/Dockerfile

@@ -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 \
+RUN --mount=type=cache,id=crank-mcp-cargo-registry,target=/usr/local/cargo/registry \
-    --mount=type=cache,target=/usr/local/cargo/git/db \
+    --mount=type=cache,id=crank-mcp-cargo-git,target=/usr/local/cargo/git/db \
-    --mount=type=cache,target=/app/target \
+    --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 \
+RUN --mount=type=cache,id=crank-mcp-cargo-registry,target=/usr/local/cargo/registry \
-    --mount=type=cache,target=/usr/local/cargo/git/db \
+    --mount=type=cache,id=crank-mcp-cargo-git,target=/usr/local/cargo/git/db \
-    --mount=type=cache,target=/app/target \
+    --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
 

apps/mcp-server/src/main.rs

@@ -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>> {
+async fn main() -> ExitCode {
-    let observability = crank_observability::init(ObservabilityConfig::from_env(
+    match main_result().await {
-        "mcp-server",
+        Ok(()) => ExitCode::SUCCESS,
-        env!("CARGO_PKG_VERSION"),
+        Err(error) => {
-        "mcp_server=info,tower_http=info",
+            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 =
+    let metrics_config = MetricsConfig::new(
-        MetricsConfig::from_env("CRANK_MCP_METRICS_BIND", "127.0.0.1:9465".parse()?)?;
+        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 secret_crypto = SecretCrypto::new(config.runtime.master_key.expose_secret())?;
-    let runtime = crank_runtime::community_from_env()?
+    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,
+        Duration::from_millis(config.refresh_ms),
-        base_url,
+        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!(
+    info!(name: "mcp.server.listening", bind_address = %config.bind_addr, "mcp-server listening");
-        name: "mcp.server.listening",
-        bind_address = %socket_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>> {
+fn init_observability(
-    if let Ok(database_url) = env::var("CRANK_DATABASE_URL") {
+    config: &ObservabilitySettings,
-        return Ok(database_url.parse::<PgConnectOptions>()?);
+) -> 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)
+        .host(&config.host)
-        .port(port)
+        .port(config.port)
-        .database(&database)
+        .database(&config.database)
-        .username(&username)
+        .username(&config.username)
-        .password(&password))
+        .password(config.password.expose_secret()))
 }
 
-fn mcp_api_rate_limit_config_from_env() -> Result<RequestRateLimitConfig, Box<dyn std::error::Error>>
+fn runtime_cache_config(
-{
+    config: &McpProcessConfig,
-    let requests_per_second = env::var("CRANK_MCP_RATE_LIMIT_RPS")
+) -> Result<RuntimeCacheConfig, crank_runtime::RuntimeCacheConfigError> {
-        .ok()
+    RuntimeCacheConfig::try_new(
-        .and_then(|value| value.parse::<u32>().ok())
+        match config.runtime.cache.backend {
-        .unwrap_or(60);
+            ConfigCacheBackend::Memory => CacheBackend::Memory,
-    let burst = env::var("CRANK_MCP_RATE_LIMIT_BURST")
+            ConfigCacheBackend::Valkey => CacheBackend::Valkey,
-        .ok()
+            ConfigCacheBackend::Redis => CacheBackend::Redis,
-        .and_then(|value| value.parse::<u32>().ok())
+        },
-        .unwrap_or(120);
+        config
-
+            .runtime
-    Ok(RequestRateLimitConfig::new(requests_per_second, burst)?)
+            .cache
+            .url
+            .as_ref()
+            .map(|value| value.expose_secret().to_owned()),
+    )
 }

apps/mcp-server/tests/config_startup.rs

@@ -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);
+}

apps/mcp-server/tests/integration.rs

@@ -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;
 }

apps/mcp-server/tests/integration/common.rs

@@ -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()
 }
 

apps/mcp-server/tests/integration/execution_stages.rs

@@ -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()?;

apps/mcp-server/tests/integration/jsonrpc_correlation.rs

@@ -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);
+}

apps/mcp-server/tests/integration/request_context.rs

@@ -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)]

apps/mcp-server/tests/integration/transport_protocol.rs

@@ -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")]

apps/ui/js/api.js

@@ -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;

apps/ui/playwright.config.js

@@ -26,10 +26,14 @@ module.exports = defineConfig({
     : {
         command: 'bash scripts/playwright-stack.sh',
         cwd: __dirname,
-        url: `${baseURL}/login`,
+      url: `${baseURL}/login`,
-        timeout: 600_000,
+      timeout: 600_000,
-        reuseExistingServer: false,
+      reuseExistingServer: false,
+      gracefulShutdown: {
+        signal: 'SIGTERM',
+        timeout: 10_000,
       },
+    },
   projects: [
     {
       name: 'chromium',

apps/ui/scripts/playwright-stack.sh

@@ -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,7 +148,11 @@ done
 
 (
   cd "$ROOT_DIR"
-  cargo run -p mcp-server >"$LOG_DIR/mcp-server.log" 2>&1
+  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"
 

apps/ui/tests/e2e/observability.spec.js

@@ -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 });
+});

crates/crank-adapter-rest/src/client.rs

@@ -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,28 +102,48 @@ impl RestAdapter {
         &self,
         target: &RestTarget,
         request: &RestRequest,
+        trusted_context: Option<&RuntimeRequestContext>,
     ) -> Result<RestResponse, RestAdapterError> {
-        let url = build_url(target, request)?;
-        self.policy.validate_url(&url)?;
-        let mut headers = build_headers(target, request)?;
-        apply_current_trace_context(&mut headers);
-        let client =
-            self.client
-                .as_ref()
-                .map_err(|details| RestAdapterError::InvalidConfiguration {
-                    details: details.to_string(),
-                })?;
-        let mut builder = client
-            .request(to_reqwest_method(target.method), url)
-            .headers(headers)
-            .timeout(Duration::from_millis(request.timeout_ms));
-
-        if let Some(body) = &request.body {
-            builder = builder.json(body);
-        }
-
         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()
+                    .map_err(|details| RestAdapterError::InvalidConfiguration {
+                        details: details.to_string(),
+                    })?;
+            let mut builder = client
+                .request(to_reqwest_method(target.method), url)
+                .headers(headers)
+                .timeout(Duration::from_millis(request.timeout_ms));
+
+            if let Some(body) = &request.body {
+                builder = builder.json(body);
+            }
+
             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> {
+    pub fn try_new(
-        let max_response_bytes = match env::var("CRANK_OUTBOUND_MAX_RESPONSE_BYTES") {
+        allowed_hosts: Vec<String>,
-            Ok(value) => {
+        denied_hosts: Vec<String>,
-                value
+        max_response_bytes: usize,
-                    .parse::<usize>()
+    ) -> Result<Self, RestAdapterError> {
-                    .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(),
-                });
-            }
-        };
         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")?,
+            allowed_hosts: validate_host_patterns(allowed_hosts)?,
-            denied_hosts: host_patterns_from_env("CRANK_OUTBOUND_DENIED_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> {
+fn validate_host_patterns(
-    let value = match env::var(name) {
+    values: impl IntoIterator<Item = String>,
-        Ok(value) => value,
+) -> Result<Vec<String>, RestAdapterError> {
-        Err(env::VarError::NotPresent) => return Ok(Vec::new()),
+    values
-        Err(error) => {
+        .into_iter()
-            return Err(RestAdapterError::InvalidConfiguration {
-                details: error.to_string(),
-            });
-        }
-    };
-    value
-        .split(',')
-        .map(str::trim)
-        .filter(|value| !value.is_empty())
         .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 {
+fn is_reserved_correlation_header(name: &HeaderName) -> bool {
-    matches!(name.as_str(), "traceparent" | "tracestate" | "baggage")
+    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));
     });

crates/crank-adapter-rest/src/lib.rs

@@ -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,

crates/crank-adapter-rest/tests/integration/client.rs

@@ -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")]

crates/crank-community-mcp/src/app.rs

@@ -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,16 +1123,17 @@ 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 =
-        .with_response_cache_scope(
+        RuntimeRequestContext::from_correlation(transport_correlation)
-            tool.workspace_id.as_str().to_owned(),
+            .with_response_cache_scope(
-            tool.agent_id.as_str().to_owned(),
+                tool.workspace_id.as_str().to_owned(),
-        )
+                tool.agent_id.as_str().to_owned(),
-        .with_metering_context(
+            )
-            tool.workspace_id.clone(),
+            .with_metering_context(
-            Some(tool.agent_id.clone()),
+                tool.workspace_id.clone(),
-            InvocationSource::AgentToolCall,
+                Some(tool.agent_id.clone()),
-        );
+                InvocationSource::AgentToolCall,
+            );
     if let Some(token) = execution.confirmation_token {
         runtime_request_context = runtime_request_context.with_confirmation_token(token);
     }
@@ -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;

crates/crank-community-mcp/src/app/invocation_history.rs

@@ -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(),

crates/crank-community-mcp/src/app/tests.rs

@@ -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,
     );

crates/crank-community-mcp/src/app/tool_resolution.rs

@@ -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
+}

crates/crank-community-mcp/src/approval_execution.rs

@@ -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,

crates/crank-community-mcp/src/jsonrpc.rs

@@ -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": {
+        "error": error
-            "code": code,
-            "message": message.into()
-        }
     })
 }
 
+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()

crates/crank-community-mcp/src/rate_limit.rs

@@ -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,
-            }
+            }))
         }
     });
 

crates/crank-community-mcp/src/request_context.rs

@@ -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 (request_id, remote_parent) = resolve_correlation(request.headers());
-    let context = RequestContext {
-        request_id: request_id.clone(),
-    };
     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());
+    if let Some(remote_parent) = remote_parent.as_ref() {
-    request.extensions_mut().insert(context);
+        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(
-        let mut response = next.run(request).instrument(span).await;
+        context.correlation.request_id().to_string(),
-        if let Ok(value) = HeaderValue::from_str(&request_id) {
+        context.correlation.trace_id().to_string(),
-            response.headers_mut().insert(HEADER_X_REQUEST_ID, value);
+        async move {
-        }
+            let mut response = next.run(request).instrument(span).await;
-        response
+            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);
+    }
+}

crates/crank-community-mcp/src/session.rs

@@ -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

crates/crank-community-mcp/src/tool_error.rs

@@ -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(_) => {

crates/crank-community-mcp/src/tool_search.rs

@@ -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
 }

crates/crank-community-mcp/tests/integration/session.rs

@@ -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(),

crates/crank-community-mcp/tests/unit/tool_error.rs

@@ -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("Проверьте параметры вызова инструмента.")

crates/crank-config/Cargo.toml

@@ -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

crates/crank-config/src/bin/crank-config-contract.rs

@@ -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()))
+    }
+}

crates/crank-config/src/debug.rs

@@ -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()
+    }
+}

crates/crank-config/src/diagnostic.rs

@@ -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"));
+    }
+}

crates/crank-config/src/fingerprint.rs

@@ -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())
+}

crates/crank-config/src/lib.rs

@@ -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;

crates/crank-config/src/migrator.rs

@@ -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,
+    })
+}

crates/crank-config/src/render.rs

@@ -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(),
+    }
+}

crates/crank-config/src/schema.rs

@@ -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
+}

crates/crank-config/src/source.rs

@@ -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
+    }
+}

crates/crank-config/src/validation.rs

@@ -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'.'))
+}

crates/crank-config/src/value.rs

@@ -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"
+        })
+    }
+}

crates/crank-config/tests/contract.rs

@@ -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");
+}

crates/crank-config/tests/generation.rs

@@ -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"));
+}

crates/crank-config/tests/redaction.rs

@@ -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());
+}

crates/crank-core/Cargo.toml

@@ -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

crates/crank-core/src/correlation.rs

@@ -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())
+}

crates/crank-core/src/ext/protocol.rs

@@ -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 request_id: RequestId,
-    pub correlation_id: String,
+    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(),
+            request_id,
-            correlation_id: correlation_id.into(),
+            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-request-id".to_owned(), self.request_id.to_string()),
-            ("x-correlation-id".to_owned(), self.correlation_id.clone()),
+            (
+                "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()),
         ])
     }
 

crates/crank-core/src/lib.rs

@@ -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,
 };

crates/crank-core/src/observability.rs

@@ -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,

crates/crank-core/tests/correlation.rs

@@ -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(",")
+    ));
+}

crates/crank-observability/Cargo.toml

@@ -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

crates/crank-observability/src/config.rs

@@ -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}")]
+    #[error("invalid observability log filter")]
-    InvalidEnvironmentEncoding { field: &'static str },
+    InvalidFilter,
-}
-
-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 })
-        }
-    }
 }
 
 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::ServiceIdentity;
-
-    use super::{ObservabilityConfigError, ServiceIdentity, env_value_or_default};
 
     #[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"
-            }
-        ));
-    }
 }

crates/crank-observability/src/correlation.rs

@@ -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())
-    }
-}

crates/crank-observability/src/error_reporting.rs

@@ -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::{
+use crate::{RedactionLimits, ServiceIdentity, propagation::current_trace_id};
-    RedactionLimits, ServiceIdentity, propagation::current_trace_id, redaction::truncate_string,
-};
 
-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()
+    let mut tags = correlation_tags().into_iter().collect::<BTreeMap<_, _>>();
-        .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));
-        }
-    }
     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");
+    // Startup validation reserves enough room for maximum canonical IDs. They
-    event.tags.remove("trace_id");
+    // 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(
-                        let span = tracing::info_span!(target: "crank::trace", "http.request");
+                        "request-123".to_owned(),
-                        let _span_guard = span.enter();
+                        "0af7651916cd43dd8448eb211c80319c".to_owned(),
-                        capture_critical_error(CriticalErrorCategory::DataIntegrity);
+                        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");

crates/crank-observability/src/lib.rs

@@ -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};

crates/crank-observability/src/lifecycle.rs

@@ -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,
+    RedactionLimitsError, SentryConfig, SentryConfigError,
-    instrumentation::register_metric_schema, logging::build_subscriber_with_tracer,
+    error_reporting::init_sentry,
-    otlp::build_tracer_provider, prometheus::install_prometheus_recorder,
+    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 exported_tracing = build_tracer_provider(&identity, &trace_config)?;
-        let trace_config = OtlpTraceConfig::from_env()?;
+        let trace_export_enabled = exported_tracing.is_some();
-        let tracing = build_tracer_provider(&identity, &trace_config)?;
+        let (tracer_provider, tracer) =
-        let tracer = tracing.as_ref().map(|(_, tracer)| tracer.clone());
+            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)]

crates/crank-observability/src/logging.rs

@@ -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)
+            .or_else(|| current_request_correlation().1)
-            .map(|value| truncate_string(&value, self.limits.max_string_bytes));
+            .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::String(value) = fields.remove(name)? else {
-    let value = match value {
+        return None;
-        Value::String(value) => value,
-        Value::Number(value) => value.to_string(),
-        Value::Bool(value) => value.to_string(),
-        Value::Null | Value::Array(_) | Value::Object(_) => 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 {

crates/crank-observability/src/otlp.rs

@@ -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> {
+    #[allow(clippy::too_many_arguments)]
-        OtlpEnvSettings::from_env()?.into_config()
+    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();
+        .build()
-    let provider = SdkTracerProvider::builder()
-        .with_span_processor(processor)
-        .with_resource(resource)
-        .build();
-    let tracer = provider.tracer("crank");
-
-    Ok(Some((provider, tracer)))
 }
 
 #[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();

crates/crank-observability/src/prometheus.rs

@@ -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,
-        }),
-    }
-}

crates/crank-observability/tests/correlation.rs

@@ -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)
-    );
-}

crates/crank-observability/tests/json_logging.rs

@@ -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 =
+    assert!(build_subscriber(config, writer).is_err());
-        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");
 }
 
 #[test]

crates/crank-observability/tests/prometheus.rs

@@ -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",

crates/crank-observability/tests/request_correlation.rs

@@ -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
+}

crates/crank-registry/src/error.rs

@@ -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 },
 }

crates/crank-registry/src/ext.rs

@@ -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(())
-}

crates/crank-registry/src/lib.rs

@@ -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::{

crates/crank-registry/src/migrations.rs

@@ -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;
+pub use authority::{
-const BASELINE_VERSION: i32 = 1;
+    BackfillBatch, BackfillPolicy, MigrationApplyResult, MigrationAuthority, MigrationDescriptor,
-const BASELINE_CHECKSUM: &str = "crank-community-baseline-v1";
+    MigrationError, MigrationPreflight,
+};
 
-pub async fn apply_postgres(pool: &PgPool) -> Result<(), sqlx::Error> {
+use baseline_v1::{BASELINE_CHECKSUM, BASELINE_VERSION, apply_baseline};
-    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(())
-}

crates/crank-registry/src/migrations/authority.rs

@@ -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;

crates/crank-registry/src/migrations/authority_tests.rs

@@ -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");
+}

crates/crank-registry/src/migrations/baseline_v1.rs

@@ -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

crates/crank-registry/src/migrations/consolidation_v2.sql

@@ -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;

crates/crank-registry/src/migrations/request_trace_identity_v3.sql

@@ -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;